Unregister a conversation

POST

/v1/conversations/{conversationId}/unregister

curl --request POST \
  --url https://example.com/v1/conversations/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/unregister \
  --header 'Authorization: Bearer <token>'

• Same-origin — path relative to the deployment root.

A tombstone: from now on no read, list or recall of earlier conversations returns it, and no message can be added. The retention sweep removes it after the workspace’s grace.

Authorizations

• bearerAuth

Parameters

Path Parameters

conversationId

required

string format: uuid

ConversationId — opaque branded string (a UUID).

Header Parameters

Idempotency-Key

string

>= 1 characters

Caller-supplied idempotency key, scoped to the caller: the same key from someone else in the workspace 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). A request whose key store can’t be read before it runs is answered 503 idempotency-store-unavailable with Retry-After: nothing ran, so retry with the same key (from 0.3.0).

Responses

200

The conversation, with unregisteredAt.

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 workspace’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

openedBy

Who opened it: the caller’s principal (user:<id>, service_account:<id>), or, for one a turn opened, whoever the run acts for. Set by the server, never from a request’s body. Absent on conversations an older runtime opened, and when the caller had no principal; those aren’t listed by ?openedBy=me.

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

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

conversationId is not a conversation id (a UUID).

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

Example^generated

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

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

Example^generated

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

403

The caller can read the conversation, and has no write on its project (on its agent, for one from before projects).

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

Example^generated

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

404

No conversation with that id under this workspace, or it is unregistered already, or the caller may not unregister it and can’t read it: the same answer, byte for byte.

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

Example^generated

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

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

Example^generated

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

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

Example^generated

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

501

conversation-unregister-unsupported: this runtime can’t unregister conversations.

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

Example^generated

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

503

The Idempotency-Key store couldn’t be read before the request ran (idempotency-store-unavailable), so nothing was changed; Retry-After (whole seconds) says when to try again with the same key.

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

Example^generated

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

See also

• GET /v1/conversations/{conversationId}: Fetch a conversation
• POST /v1/conversations/{conversationId}/close: Close a conversation
• GET /v1/conversations/{conversationId}/messages: Read conversation messages
• Error code conversation-unregister-unsupported
• Error code idempotency-store-unavailable
• Every error code