Update a conversation

PUT

/v1/conversations/:id

PUT

/v1/conversations/:id

$ curl -X PUT https://api.runtype.com/v1/conversations/id \
>      -H "Authorization: <apiKey>" \
>      -H "Content-Type: application/json" \
>      -d '{
>   "agentId": "agent_01j9r4x0h7f9k4b2n8t6q3m5cd",
>   "messages": [
>     {
>       "content": "Book me a table for two at 7pm.",
>       "role": "user"
>     },
>     {
>       "content": "",
>       "role": "assistant",
>       "toolCalls": [
>         {
>           "toolCallId": "call_9",
>           "toolName": "create_reservation",
>           "args": {
>             "partySize": 2,
>             "time": "19:00"
>           }
>         }
>       ]
>     },
>     {
>       "content": "",
>       "role": "tool",
>       "toolResults": [
>         {
>           "toolCallId": "call_9",
>           "toolName": "create_reservation",
>           "result": null
>         }
>       ]
>     },
>     {
>       "content": "Booked. Your table for two is confirmed for 7pm.",
>       "role": "assistant"
>     }
>   ],
>   "source": {
>     "system": "custom"
>   }
> }'

1 {
2   "createdAt": "string",
3   "id": "string",
4   "messages": [
5     {
6       "content": "string",
7       "role": "system",
8       "author": {
9         "type": "end_user",
10         "externalId": "string",
11         "id": "string",
12         "name": "string"
13       },
14       "createdAt": "string",
15       "id": "string",
16       "metadata": {},
17       "toolCalls": [
18         {
19           "toolCallId": "string",
20           "toolName": "string",
21           "args": {},
22           "providerOptions": {}
23         }
24       ],
25       "toolResults": [
26         {
27           "toolCallId": "string",
28           "toolName": "string",
29           "providerOptions": {},
30           "result": null
31         }
32       ]
33     }
34   ],
35   "metadata": {},
36   "modelId": "string",
37   "ownerId": "string",
38   "source": "app",
39   "systemPrompt": "string",
40   "title": "string",
41   "updatedAt": "string",
42   "imported": true,
43   "schemaWarnings": [
44     {
45       "code": "string",
46       "field": "string",
47       "message": "string"
48     }
49   ]
50 }

Authentication

AuthorizationBearer

API key or Clerk session token

Path parameters

idstringRequired

Request

This endpoint expects an object.

agentIdstring or nullOptional1-255 characters

Null clears metadata.agentId; omit to leave it unchanged.

messageslist of objectsOptional

Full-fidelity transcript. A tool message must carry toolResults answering an assistant toolCalls entry issued earlier in the array; ids and createdAt are minted when omitted.

messagesModeenumOptionalDefaults to replace

How to apply messages. replace (the default) swaps the whole transcript. append adds them to the end, skipping any message whose id is already stored, so a chunked import can retry a chunk safely; the combined transcript is validated and must satisfy the same tool-pairing discipline.

Allowed values:

metadatamap from strings to anyOptional

modelIdstringOptional<=255 characters

ownerIdstring or nullOptional1-255 characters

Reassigns the owner (indexed owner_id column, filterable via ?ownerId=). Overrides a nested metadata.ownerId. Null clears the owner; omit to leave it unchanged.

sourceobjectOptional

Import provenance, stored as metadata.importSource.

systemPromptstringOptional

titlestringOptional<=500 characters

Response

Conversation updated

createdAtstring

idstring

messageslist of objects

metadatamap from strings to any

modelIdstring or null

ownerIdstring or null

sourceenum

systemPromptstring or null

titlestring

updatedAtstring

importedbooleanOptional

Set by POST /v1/conversations only. True when this call created the conversation (201); false when a conversation with the same source.system and source.externalId already existed and is returned unchanged (200).

schemaWarningslist of objectsOptional

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

409

Conflict Error

422

Unprocessable Entity Error

500

Internal Server Error