Skip to content
Kindgi

Open a conversation

View as Markdown
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", "projectId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "scope": {}, "participantId": "example", "metadata": {} }'

Pins (agentId, agentVersion) at open time. title defaults to "Untitled conversation" when omitted; projectId puts it in a project, which must reach the agent (lists filter by it; omitted, the agent’s own project, as for a run, or the Default project for an agent filed under none); 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, scoped to the caller: the same key from someone else in the tenant is their own request (from 0.1.5). Retries with the same key return the original response byte-identical (per docs/API-ROUTE-CONVENTIONS.md §3.1). A retry sent while the first request still runs is answered 409 idempotency-key-in-flight with Retry-After, on a runtime whose store holds keys (from 0.1.5); retry after it, and you get the first request’s answer. An answer that carries a secret (a new API key or public run token, a session token, a generated signing secret) isn’t kept: a retry gets 409 idempotency-key-replay-withheld, with the first request’s status and when it succeeded (from 0.1.5).

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
projectId

The project the conversation is in; GET /v1/conversations?scopeKind=project&scopeId=… lists it. A project of the caller’s tenant, else 400 bad-input, that reaches the agent, else 400 reference-out-of-scope. Omitted: the agent’s own project, as for a run (the tenant’s Default project for an agent filed under none).

string format: uuid
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",
  "projectId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "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
projectId

The project the conversation is in: the project of the run that opened it, or projectId on open (when omitted, the agent’s own project, or the tenant’s Default project for an agent filed under none). Absent on conversations from before Kindgi 0.1.3; those are listed only without a scope.

string format: uuid
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
unregisteredAt

When it was unregistered (POST /v1/conversations/{conversationId}/unregister). Only the unregister call returns it: reads no longer do.

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, or projectId names no project of this tenant. Or reference-out-of-scope: the agent isn’t registered in the conversation’s project, its org or the tenant (details.issues).

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"
  }
}

403

Section titled “403”

No execute on the agent; or a participantId whose memory the caller may not read (participant-not-allowed): its turns run with that participant’s memory, so opening it for someone takes being them (a person, by their user id) or write on its project.

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"
  }
}

413

Section titled “413”

The request body is over the API’s limit (request-too-large; details.maxBytes says how much).

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"
  }
}

See also