Promote Project | SpeechifyAI API

curl -X POST https://api.speechify.ai/v1/projects/proj_01jqr8x9zg5k2m3n4p5q6r7s8t/promote \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "target_project_id": "proj_01jqr8x9zg5k2m3n4p5q6r7s8t"
}'

{
  "created": {
    "agents": [
      "string"
    ],
    "tools": [
      "string"
    ],
    "knowledge_bases": [
      "string"
    ],
    "audio_assets": [
      "string"
    ],
    "webhook_endpoints": [
      "string"
    ],
    "agent_tests": [
      "string"
    ],
    "import_jobs": [
      "string"
    ]
  },
  "reused": {
    "tools": [
      "string"
    ]
  },
  "needs_attention": [
    {
      "kind": "agent",
      "id": "tool_01jqr8x9zg5k2m3n4p5q6r7s8t",
      "reason": "credential_not_attached",
      "message": "string"
    }
  ]
}

Copy this project’s configuration into another project in the same workspace, creating equivalent resources there. Use it to move a staging environment into production, or to seed one client’s project from another’s.

Copied: agents with every setting (prompt, voice, model, memory and consent settings, builtin tools, tool and knowledge-base bindings, the draft and published flow versions, test definitions), tool definitions, knowledge bases with their folders (URL sources are re-imported in the target through the normal import path, so the response lists the import jobs to poll), audio assets (the object is copied), and the webhook endpoints scoped to the source.

Never copied: vault credentials, API keys and service accounts, phone numbers and SIP trunks, conversations, callers, memories, call and test history, batch calls, member grants, spend limits, uploaded or pasted knowledge-base documents, and every secret. A copied tool or agent that referenced a credential has the reference cleared, every server-minted signing secret is minted fresh, and each such item is listed under needs_attention so nothing is silently half-configured.

A copy keeps its name. Where the target already holds a resource of the same kind and name, the copy is suffixed (name (2), or name_2 for tools) and listed under needs_attention with reason renamed; a target tool whose definition is identical to the source’s is bound instead of duplicated and appears under reused.

The copy runs in one transaction. A project holding more than 200 resources (agents, tools, knowledge bases, URL sources, audio assets, webhook endpoints and tests together) answers 409 project_too_large_to_promote. Send an Idempotency-Key header to make a retry safe: the first manifest is replayed rather than the project copied twice. Both projects must be reachable to the caller; a project-pinned credential cannot promote.

Copy this project's configuration into another project in the same workspace, creating equivalent resources there. Use it to move a staging environment into production, or to seed one client's project from another's. Copied: agents with every setting (prompt, voice, model, memory and consent settings, builtin tools, tool and knowledge-base bindings, the draft and published flow versions, test definitions), tool definitions, knowledge bases with their folders (URL sources are re-imported in the target through the normal import path, so the response lists the import jobs to poll), audio assets (the object is copied), and the webhook endpoints scoped to the source. Never copied: vault credentials, API keys and service accounts, phone numbers and SIP trunks, conversations, callers, memories, call and test history, batch calls, member grants, spend limits, uploaded or pasted knowledge-base documents, and every secret. A copied tool or agent that referenced a credential has the reference cleared, every server-minted signing secret is minted fresh, and each such item is listed under `needs_attention` so nothing is silently half-configured. A copy keeps its name. Where the target already holds a resource of the same kind and name, the copy is suffixed (`name (2)`, or `name_2` for tools) and listed under `needs_attention` with reason `renamed`; a target tool whose definition is identical to the source's is bound instead of duplicated and appears under `reused`. The copy runs in one transaction. A project holding more than 200 resources (agents, tools, knowledge bases, URL sources, audio assets, webhook endpoints and tests together) answers `409 project_too_large_to_promote`. Send an `Idempotency-Key` header to make a retry safe: the first manifest is replayed rather than the project copied twice. Both projects must be reachable to the caller; a project-pinned credential cannot promote.

Authentication

AuthorizationBearer

Enter your API key with the Bearer prefix, e.g. ‘Bearer sk_…’.

Path parameters

project_idstringRequired

The source project whose configuration is copied.

Headers

Idempotency-KeystringOptional<=255 characters

A client-generated key (an opaque string, max 255 chars) that makes a side-effect POST safe to retry: the server runs the operation exactly once and replays the first response (its status and body) for 24 hours. Reusing a key with a different request body, or while the first request is still in flight, returns 409 idempotency_conflict. A replayed response carries the Idempotent-Replayed: true header.

A client-generated key (an opaque string, max 255 chars) that makes a side-effect POST safe to retry: the server runs the operation exactly once and replays the first response (its status and body) for 24 hours. Reusing a key with a different request body, or while the first request is still in flight, returns `409 idempotency_conflict`. A replayed response carries the `Idempotent-Replayed: true` header.

Request

This endpoint expects an object.

target_project_idstringRequiredformat: "^proj_[0-9a-hjkmnp-tv-z]{26}$"

The project to copy into. Must differ from the source and belong to the same workspace.

Response headers

Speechify-Request-IdstringOptional

Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends a Speechify-Request-Id request header the server echoes it back (sanitized and length-capped) so one logical request can be traced end-to-end; otherwise the server generates a fresh value. Log it on every response and quote it in support requests

it is the stable handle that ties your observation to Speechify’s server-side logs, and it matches the request_id field in the error envelope.

The legacy alias X-Request-ID carries the same value and is still accepted on requests, until 2027-07-24. Prefer the un-prefixed name (RFC 6648).

Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends a `Speechify-Request-Id` request header the server echoes it back (sanitized and length-capped) so one logical request can be traced end-to-end; otherwise the server generates a fresh value. Log it on every response and quote it in support requests - it is the stable handle that ties your observation to Speechify's server-side logs, and it matches the `request_id` field in the error envelope. The legacy alias `X-Request-ID` carries the same value and is still accepted on requests, until 2027-07-24. Prefer the un-prefixed name (RFC 6648).

Response

What the promote created, reused, and left for a person to finish.

createdobject

Ids minted in the target, by kind. Each list is empty, never absent, when nothing of that kind was copied.

reusedobject

Target resources bound instead of copied because an identical definition already existed there.

needs_attentionlist of objects

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

409

Conflict Error