Create conversation

tong_conversation_create

Create a saved resource in your Tong account using the fields below.

POST/v1/tools/tong_conversation_create/operations

Request example#

curl -X POST 'https://platform.tongai.io/v1/tools/tong_conversation_create/operations' \  -H "Authorization: Bearer $TONG_API_KEY" \  -H "Content-Type: application/json" \  -H "Idempotency-Key: 45be69f1-c266-4a09-a82c-bf3c6303eb03" \  -d '{  "input": {    "body": {      "title": "Blue hour film"    }  }}'

Configuration

curl --version

Permissions#

Use a server-side API key for your account, or OAuth for each customer’s account. Never send keys in prompts or tool arguments.

conversations:write

Request body#

REST requests wrap the tool arguments in input. MCP calls send the same arguments directly.

bodyobjectRequired

Show nested fields

titlestringOptional

Minimum length: 1 characters.

Maximum length: 100 characters.

Example"Blue hour film"

Request headers#

HTTP

Authorization: Bearer $TONG_API_KEYContent-Type: application/jsonIdempotency-Key: 45be69f1-c266-4a09-a82c-bf3c6303eb03

Keep one UUID for each intended action and reuse it after a timeout or retry. A different input with the same UUID is rejected.

Response fields#

An accepted request is not a finished generation. Track the saved job until its output is ready.

Response

Accepted means the request was saved. Read its operation to follow execution.

JSON

{  "id": "e8aa0a87-6cd9-42eb-975a-b72bf43218c8",  "tool": "tong_conversation_create",  "category": "conversation",  "channel": "api",  "state": "queued",  "status": "accepted",  "stage": "admission",  "dispatch_status": "pending",  "created_at": "2026-10-22T09:00:00.000Z",  "updated_at": "2026-10-22T09:00:00.000Z",  "detail_expires_at": null,  "detail_expired": false,  "timing": {    "dispatch_started_at": null,    "acknowledged_at": null,    "completed_at": null,    "dispatch_acknowledgement_ms": null,    "end_to_end_ms": null  },  "review": null,  "result": null,  "error": null,  "billing": {    "status": "pending",    "usage_credits": "0.000000",    "wallet_debited_credits": "0.000000"  }}

idstringRequired

The unique ID of the saved operation.

A UUID, for example e8aa0a87-6cd9-42eb-975a-b72bf43218c8.

toolstringRequired

categorystringRequired

channelstringRequired

Allowed values"api""mcp"

statestringRequired

The current execution state of the saved work.

Allowed values"queued""running""waiting""needs_review""paused""reconciling""succeeded""failed""cancelled"

statusstringRequired

The overall status to use when tracking the operation.

Allowed values"accepted""running""needs_review""paused""reconciling""succeeded""failed""cancelled"

stagestringRequired

The current phase of the operation.

Allowed values"admission""dispatch""review""generation""reconciliation""complete"

dispatch_statusstringRequired

Whether the tool accepted the request. An acknowledgement does not mean generation is complete.

Allowed values"pending""unknown""acknowledged"

created_atstringRequired

ISO 8601 date and time, for example 2026-10-22T09:00:00Z.

updated_atstringRequired

ISO 8601 date and time, for example 2026-10-22T09:00:00Z.

detail_expires_atstring | nullRequired

When stored operation details expire. A null value means no expiry is currently set.

ISO 8601 date and time, for example 2026-10-22T09:00:00Z.

detail_expiredbooleanRequired

Whether the stored operation details have expired.

timingobjectRequired

Timestamps and elapsed times for tracking this operation.

Show nested fields

dispatch_started_atstring | nullRequired

ISO 8601 date and time, for example 2026-10-22T09:00:00Z.

acknowledged_atstring | nullRequired

ISO 8601 date and time, for example 2026-10-22T09:00:00Z.

completed_atstring | nullRequired

ISO 8601 date and time, for example 2026-10-22T09:00:00Z.

dispatch_acknowledgement_msnumber | nullRequired

Minimum: 0.

end_to_end_msnumber | nullRequired

Minimum: 0.

reviewJSON | nullRequired

Review information when the operation needs human input; otherwise null.

resultJSON | nullRequired

The output returned by this tool, or null while no output is available.

errorobject | nullRequired

The public error code if the operation failed; otherwise null.

Show nested fields

codestringRequired

billingobjectRequired

Customer credit usage and wallet charges. Output readiness and billing settlement are separate.

Show nested fields

statusstringRequired

Allowed values"none""pending""settled""released""reconciling"

usage_creditsstringRequired

A decimal string with six decimal places, for example 1.250000.

wallet_debited_creditsstringRequired

A decimal string with six decimal places, for example 1.250000.

released_creditsstringOptional

A decimal string with six decimal places, for example 1.250000.

refunded_creditsstringOptional

A decimal string with six decimal places, for example 1.250000.

unfunded_creditsstringOptional

A decimal string with six decimal places, for example 1.250000.

pending_creditsstringOptional

A decimal string with six decimal places, for example 1.250000.

tokensobjectOptional

Show nested fields

inputnumberOptional

Minimum: 0.

outputnumberOptional

Minimum: 0.

cachednumberOptional

Minimum: 0.

cache_writenumberOptional

Minimum: 0.

componentsobject[]Optional

Show nested fields

idstringOptional

source_idstringRequired

toolstringRequired

modelstring | nullRequired

channelstringRequired

Allowed values"api""mcp"

credential_idstringRequired

kindstringRequired

Allowed values"text_pool""reasoning""generation"

usage_creditsstringRequired

A decimal string with six decimal places, for example 1.250000.

wallet_debited_creditsstringRequired

A decimal string with six decimal places, for example 1.250000.

evidence_atstringOptional

ISO 8601 date and time, for example 2026-10-22T09:00:00Z.

updated_atstringOptional

ISO 8601 date and time, for example 2026-10-22T09:00:00Z.

quoteobjectOptional

The quoted configuration, price and submission values, when a quote is available.

Show nested fields

idstringRequired

A UUID, for example e8aa0a87-6cd9-42eb-975a-b72bf43218c8.

operation_idstringRequired

A UUID, for example e8aa0a87-6cd9-42eb-975a-b72bf43218c8.

toolstringRequired

operationstring | nullRequired

modelstring | nullRequired

configurationobjectRequired

submit_valuestringRequired

submit_fieldstringRequired

quoted_creditsstring | nullRequired

A decimal string with six decimal places, for example 1.250000.

expires_atstring | nullRequired

ISO 8601 date and time, for example 2026-10-22T09:00:00Z.

Requests and logsAn accepted request is not a finished generation. Track the saved job until its output is ready.Credits and billingFollow quoted prices, actual usage and settled customer credits.

MCP call#

JSON

{  "jsonrpc": "2.0",  "id": 1,  "method": "tools/call",  "params": {    "name": "tong_conversation_create",    "arguments": {      "body": {        "title": "Blue hour film"      }    },    "_meta": {      "io.tongai/idempotency-key": "45be69f1-c266-4a09-a82c-bf3c6303eb03"    }  }}

REST requests wrap the tool arguments in input. MCP calls send the same arguments directly.

Response

JSON

{  "jsonrpc": "2.0",  "id": 1,  "result": {    "structuredContent": {      "id": "e8aa0a87-6cd9-42eb-975a-b72bf43218c8",      "tool": "tong_conversation_create",      "category": "conversation",      "channel": "mcp",      "state": "queued",      "status": "accepted",      "stage": "admission",      "dispatch_status": "pending",      "created_at": "2026-10-22T09:00:00.000Z",      "updated_at": "2026-10-22T09:00:00.000Z",      "detail_expires_at": null,      "detail_expired": false,      "timing": {        "dispatch_started_at": null,        "acknowledged_at": null,        "completed_at": null,        "dispatch_acknowledgement_ms": null,        "end_to_end_ms": null      },      "review": null,      "result": null,      "error": null,      "billing": {        "status": "pending",        "usage_credits": "0.000000",        "wallet_debited_credits": "0.000000"      }    },    "content": [      {        "type": "text",        "text": "{\"id\":\"e8aa0a87-6cd9-42eb-975a-b72bf43218c8\",\"tool\":\"tong_conversation_create\",\"category\":\"conversation\",\"channel\":\"mcp\",\"state\":\"queued\",\"status\":\"accepted\",\"stage\":\"admission\",\"dispatch_status\":\"pending\",\"created_at\":\"2026-10-22T09:00:00.000Z\",\"updated_at\":\"2026-10-22T09:00:00.000Z\",\"detail_expires_at\":null,\"detail_expired\":false,\"timing\":{\"dispatch_started_at\":null,\"acknowledged_at\":null,\"completed_at\":null,\"dispatch_acknowledgement_ms\":null,\"end_to_end_ms\":null},\"review\":null,\"result\":null,\"error\":null,\"billing\":{\"status\":\"pending\",\"usage_credits\":\"0.000000\",\"wallet_debited_credits\":\"0.000000\"}}"      }    ]  }}

Errors and limits#

HTTP	Error	Recovery
`400`	Invalid request`REQUEST_INVALID`	Correct the fields identified by the error before trying again.
`401`	Invalid credential`CREDENTIAL_INVALID`	Check the credential, its expiry and whether it has been revoked.
`402`	Insufficient credits`INSUFFICIENT_CREDITS`	Add credits to the account that owns the credential, then continue the saved work.
`403`	Permission denied`SCOPE_REQUIRED`	Use a credential with the required scopes and access to the selected resource.
`404`	Resource unavailable`RESOURCE_UNAVAILABLE`	Check the resource ID and that it belongs to the authorized account.
`409`	Intent conflict`IDEMPOTENCY_CONFLICT`	Reuse an intent only with its original request. Use a new UUID for a different action.
`429`	Rate limited`RATE_LIMITED`	Wait for Retry-After before retrying the same intended request.
`503`	Temporarily unavailable`DEPENDENCY_UNAVAILABLE`	Wait for Retry-After and retry with the same intent. Check the saved operation after a timeout.

Errors and rate limitsUnderstand error responses, retry safely and recover from failed generations.IdempotencyKeep one UUID for each intended action and reuse it after a timeout or retry. A different input with the same UUID is rejected.

Get conversationRead the selected owned resource or current workflow state without starting a new generation.Conversation messagesRead the selected owned resource or current workflow state without starting a new generation.List conversationsRead the selected owned resource or current workflow state without starting a new generation.Update conversationUpdate the selected owned resource with the fields below.Delete conversationRemove the selected owned resource. Read the current resource and its consequences before calling this tool.

Create conversation

Request example#

Permissions#

Request body#

Request headers#

Response fields#

MCP call#

Response

Errors and limits#

Related tools#