Create a conversation | Runtype Documentation

curl -X POST https://api.runtype.com/v1/conversations \
     -H "Authorization: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "metadata": {
    "topic": "general"
  },
  "modelId": "gpt-4",
  "systemPrompt": "You are a helpful assistant.",
  "title": "New Chat"
}'

{
  "createdAt": "string",
  "id": "string",
  "messages": [
    {
      "content": "string",
      "role": "system",
      "author": {
        "type": "end_user",
        "externalId": "string",
        "id": "string",
        "name": "string"
      },
      "createdAt": "string",
      "id": "string",
      "metadata": {},
      "model": "string",
      "toolCalls": [
        {
          "toolCallId": "string",
          "toolName": "string",
          "args": {},
          "providerOptions": {}
        }
      ],
      "toolResults": [
        {
          "toolCallId": "string",
          "toolName": "string",
          "providerOptions": {},
          "result": null
        }
      ]
    }
  ],
  "metadata": {},
  "modelId": "string",
  "ownerId": "string",
  "source": "app",
  "systemPrompt": "string",
  "title": "string",
  "updatedAt": "string",
  "imported": true,
  "schemaWarnings": [
    {
      "code": "string",
      "field": "string",
      "message": "string"
    }
  ]
}

Authentication

AuthorizationBearer

API key or Clerk session token

Request

This endpoint expects an object.

agentIdstringOptional1-255 characters

Agent (agent_…) this conversation belongs to, stored as metadata.agentId. Must name an agent the caller owns.

messageslist of objectsOptionalDefaults to []

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.

metadatamap from strings to anyOptionalDefaults to {}

modelIdstringOptional<=255 characters

ownerIdstring or nullOptional1-255 characters

Owner key for this conversation, stored in the indexed owner_id column and filterable via ?ownerId=. Overrides a nested metadata.ownerId. Null means no owner.

sourceobjectOptional

Import provenance, stored as metadata.importSource.

systemPromptstringOptional

titlestringOptional<=500 charactersDefaults to New Chat

Response

A conversation with this source.system and source.externalId was already imported. Nothing was created and the existing conversation is returned with imported: false.

createdAtstring

idstring

messageslist of objects

metadatamap from strings to any

modelIdstring or null

ownerIdstring or null

sourceenum

Allowed values:

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

422

Unprocessable Entity Error

500

Internal Server Error

503

Service Unavailable Error