Skip to content
Kindgi

Open a conversation

POST
/v1/conversations
curl --request POST \
  --url https://example.com/v1/conversations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "agentId": "example", "agentVersion": "example", "title": "example", "scope": {}, "participantId": "example", "metadata": {} }'

Pins (agentId, agentVersion) at open time. title defaults to "Untitled conversation" when omitted; scope accepts arbitrary JSON.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Header Parameters

Section titled “Header Parameters”
Idempotency-Key
string
>= 1 characters

Caller-supplied idempotency key. Retries with the same key return the original response byte-identical (per docs/API-ROUTE-CONVENTIONS.md §3.1).

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
agentId
required

AgentId.

string
>= 1 characters
agentVersion
required

Semver — pinned at open time.

string
>= 1 characters
title

Optional. Defaults to "Untitled conversation" when omitted.

string
scope

Structural scope (project id, matter id, etc.). Treated opaquely by the runtime.

object
key
additional properties
any
participantId
string
metadata
object
key
additional properties
any
Examplegenerated
{
  "agentId": "example",
  "agentVersion": "example",
  "title": "example",
  "scope": {},
  "participantId": "example",
  "metadata": {}
}

Responses

Section titled “Responses”

201

Section titled “201”

Conversation opened.

Media typeapplication/json
object
id
required

ConversationId.

string format: uuid
tenantId
required
string format: uuid
agentId
required
string
agentVersion
required

Semver.

string
title
required
string
participantId
string
scope
required

Free-form scope object (currently { tenantId } in tests; enterprises extend with matterId, engagementId, etc.).

object
key
additional properties
any
status
required

Lifecycle status derived from closedAt: open when null, closed otherwise.

string
Allowed values: open closed
openedAt
required
string format: date-time
closedAt
string format: date-time
turnCount
required
integer
lastMessageAt
string format: date-time
metadata
object
key
additional properties
any
Example
{
  "status": "open"
}

400

Section titled “400”

Malformed request body.

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

401

Section titled “401”

Missing / malformed / expired / revoked bearer token.

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

409

Section titled “409”

Idempotency-Key was reused with a different body, or resource-state conflict.

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

500

Section titled “500”

Server error (unmapped domain code or framework crash).

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}