Agent
Stream typed grounded agent events
POST/agent/conversations/{id}/messages
SSE event name equals payload.type; SSE id equals payload.id. Sequence strictly increases within one message. POST never auto-reconnects. Resume exact body/key with Last-Event-ID after reconciling GET snapshot. EOF before done means unknown outcome. Stream never executes a proposed domain write.
Authentication
sessionCookie / bearerAuth
__Host-krin_session
HttpOnly Secure SameSite=Lax console session. Writes require CSRF token and Origin validation.
bearer
Organization-scoped API access token. Server intersects current membership and token scopes.
Required roles
advertiser:owneradvertiser:manageradvertiser:analystpublisher:ownerpublisher:integration_managerpublisher:analystinternal:organization_ownerinternal:support_operatorinternal:finance_operatorinternal:risk_operator
Human approval required
Getting startedParameters
id
path · Required · string
id scoped to the authenticated identity and organization.
Inspect JSON schema
{
"type": "string",
"pattern": "^[a-z][a-z0-9]*_[A-Za-z0-9_-]+$",
"maxLength": 128
}Idempotency-Key
header · Required · string
UUID per user intent. Retain body/key through retries and unknown outcomes for at least 7 days.
Inspect JSON schema
{
"type": "string",
"format": "uuid"
}X-CSRF-Token
header · Optional · string
Required for cookie-authenticated writes; bearer callers omit. Validated with Origin on server.
Inspect JSON schema
{
"type": "string",
"minLength": 1,
"maxLength": 256
}Last-Event-ID
header · Optional · string
Resume only the same message/body/idempotency key. Unknown or expired cursor returns 409 agent_resume_expired.
Inspect JSON schema
{
"type": "string",
"pattern": "^[a-z][a-z0-9]*_[A-Za-z0-9_-]+$",
"maxLength": 128
}Request body
application/json · Required
typeRequiredstring"text"textRequiredstringminLength:
1maxLength:
8000
Inspect JSON schema
{
"type": "object",
"additionalProperties": false,
"required": [
"type",
"text"
],
"properties": {
"type": {
"type": "string",
"enum": [
"text"
]
},
"text": {
"type": "string",
"minLength": 1,
"maxLength": 8000
}
}
}Responses
200Stream typed grounded agent events
X-Request-Id · Opaque trace reference; never contains user data.
Cache-Control · Disable intermediate caching.
X-Accel-Buffering · Disable proxy buffering.
text/event-stream
Inspect JSON schema
{
"oneOf": [
{
"$ref": "#/components/schemas/AgentAckEvent"
},
{
"$ref": "#/components/schemas/AgentStateEvent"
},
{
"$ref": "#/components/schemas/AgentTextEvent"
},
{
"$ref": "#/components/schemas/AgentTubeEvent"
},
{
"$ref": "#/components/schemas/AgentCardEvent"
},
{
"$ref": "#/components/schemas/AgentConfirmEvent"
},
{
"$ref": "#/components/schemas/AgentErrorEvent"
},
{
"$ref": "#/components/schemas/AgentDoneEvent"
}
],
"discriminator": {
"propertyName": "type",
"mapping": {
"ack": "#/components/schemas/AgentAckEvent",
"state": "#/components/schemas/AgentStateEvent",
"text.delta": "#/components/schemas/AgentTextEvent",
"tube.update": "#/components/schemas/AgentTubeEvent",
"card": "#/components/schemas/AgentCardEvent",
"confirm.request": "#/components/schemas/AgentConfirmEvent",
"error": "#/components/schemas/AgentErrorEvent",
"done": "#/components/schemas/AgentDoneEvent"
}
}
}400Invalid request
X-Request-Id · Opaque trace reference; never contains user data.
application/problem+json
typeRequiredstringformat:
urititleRequiredstringminLength:
1maxLength:
200statusRequiredintegerminimum:
400maximum:
599codeRequiredstringminLength:
1maxLength:
80pattern:
^[a-z][a-z0-9_]+$detailOptionalstringminLength:
1maxLength:
2000instanceOptionalstringminLength:
1maxLength:
512errorsOptionalobject
Inspect JSON schema
{
"type": "object",
"additionalProperties": false,
"required": [
"type",
"title",
"status",
"code"
],
"properties": {
"type": {
"type": "string",
"format": "uri"
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"status": {
"type": "integer",
"minimum": 400,
"maximum": 599
},
"code": {
"type": "string",
"minLength": 1,
"maxLength": 80,
"pattern": "^[a-z][a-z0-9_]+$"
},
"detail": {
"type": "string",
"minLength": 1,
"maxLength": 2000
},
"instance": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"errors": {
"type": "object",
"additionalProperties": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 300
},
"minItems": 1,
"maxItems": 10
}
}
}
}401Authentication required
X-Request-Id · Opaque trace reference; never contains user data.
application/problem+json
typeRequiredstringformat:
urititleRequiredstringminLength:
1maxLength:
200statusRequiredintegerminimum:
400maximum:
599codeRequiredstringminLength:
1maxLength:
80pattern:
^[a-z][a-z0-9_]+$detailOptionalstringminLength:
1maxLength:
2000instanceOptionalstringminLength:
1maxLength:
512errorsOptionalobject
Inspect JSON schema
{
"type": "object",
"additionalProperties": false,
"required": [
"type",
"title",
"status",
"code"
],
"properties": {
"type": {
"type": "string",
"format": "uri"
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"status": {
"type": "integer",
"minimum": 400,
"maximum": 599
},
"code": {
"type": "string",
"minLength": 1,
"maxLength": 80,
"pattern": "^[a-z][a-z0-9_]+$"
},
"detail": {
"type": "string",
"minLength": 1,
"maxLength": 2000
},
"instance": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"errors": {
"type": "object",
"additionalProperties": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 300
},
"minItems": 1,
"maxItems": 10
}
}
}
}403Insufficient permission
X-Request-Id · Opaque trace reference; never contains user data.
application/problem+json
typeRequiredstringformat:
urititleRequiredstringminLength:
1maxLength:
200statusRequiredintegerminimum:
400maximum:
599codeRequiredstringminLength:
1maxLength:
80pattern:
^[a-z][a-z0-9_]+$detailOptionalstringminLength:
1maxLength:
2000instanceOptionalstringminLength:
1maxLength:
512errorsOptionalobject
Inspect JSON schema
{
"type": "object",
"additionalProperties": false,
"required": [
"type",
"title",
"status",
"code"
],
"properties": {
"type": {
"type": "string",
"format": "uri"
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"status": {
"type": "integer",
"minimum": 400,
"maximum": 599
},
"code": {
"type": "string",
"minLength": 1,
"maxLength": 80,
"pattern": "^[a-z][a-z0-9_]+$"
},
"detail": {
"type": "string",
"minLength": 1,
"maxLength": 2000
},
"instance": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"errors": {
"type": "object",
"additionalProperties": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 300
},
"minItems": 1,
"maxItems": 10
}
}
}
}404Resource not found
X-Request-Id · Opaque trace reference; never contains user data.
application/problem+json
typeRequiredstringformat:
urititleRequiredstringminLength:
1maxLength:
200statusRequiredintegerminimum:
400maximum:
599codeRequiredstringminLength:
1maxLength:
80pattern:
^[a-z][a-z0-9_]+$detailOptionalstringminLength:
1maxLength:
2000instanceOptionalstringminLength:
1maxLength:
512errorsOptionalobject
Inspect JSON schema
{
"type": "object",
"additionalProperties": false,
"required": [
"type",
"title",
"status",
"code"
],
"properties": {
"type": {
"type": "string",
"format": "uri"
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"status": {
"type": "integer",
"minimum": 400,
"maximum": 599
},
"code": {
"type": "string",
"minLength": 1,
"maxLength": 80,
"pattern": "^[a-z][a-z0-9_]+$"
},
"detail": {
"type": "string",
"minLength": 1,
"maxLength": 2000
},
"instance": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"errors": {
"type": "object",
"additionalProperties": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 300
},
"minItems": 1,
"maxItems": 10
}
}
}
}409State changed
X-Request-Id · Opaque trace reference; never contains user data.
application/problem+json
typeRequiredstringformat:
urititleRequiredstringminLength:
1maxLength:
200statusRequiredintegerminimum:
400maximum:
599codeRequiredstringminLength:
1maxLength:
80pattern:
^[a-z][a-z0-9_]+$detailOptionalstringminLength:
1maxLength:
2000instanceOptionalstringminLength:
1maxLength:
512errorsOptionalobject
Inspect JSON schema
{
"type": "object",
"additionalProperties": false,
"required": [
"type",
"title",
"status",
"code"
],
"properties": {
"type": {
"type": "string",
"format": "uri"
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"status": {
"type": "integer",
"minimum": 400,
"maximum": 599
},
"code": {
"type": "string",
"minLength": 1,
"maxLength": 80,
"pattern": "^[a-z][a-z0-9_]+$"
},
"detail": {
"type": "string",
"minLength": 1,
"maxLength": 2000
},
"instance": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"errors": {
"type": "object",
"additionalProperties": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 300
},
"minItems": 1,
"maxItems": 10
}
}
}
}413Payload too large
X-Request-Id · Opaque trace reference; never contains user data.
application/problem+json
typeRequiredstringformat:
urititleRequiredstringminLength:
1maxLength:
200statusRequiredintegerminimum:
400maximum:
599codeRequiredstringminLength:
1maxLength:
80pattern:
^[a-z][a-z0-9_]+$detailOptionalstringminLength:
1maxLength:
2000instanceOptionalstringminLength:
1maxLength:
512errorsOptionalobject
Inspect JSON schema
{
"type": "object",
"additionalProperties": false,
"required": [
"type",
"title",
"status",
"code"
],
"properties": {
"type": {
"type": "string",
"format": "uri"
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"status": {
"type": "integer",
"minimum": 400,
"maximum": 599
},
"code": {
"type": "string",
"minLength": 1,
"maxLength": 80,
"pattern": "^[a-z][a-z0-9_]+$"
},
"detail": {
"type": "string",
"minLength": 1,
"maxLength": 2000
},
"instance": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"errors": {
"type": "object",
"additionalProperties": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 300
},
"minItems": 1,
"maxItems": 10
}
}
}
}415Unsupported media type
X-Request-Id · Opaque trace reference; never contains user data.
application/problem+json
typeRequiredstringformat:
urititleRequiredstringminLength:
1maxLength:
200statusRequiredintegerminimum:
400maximum:
599codeRequiredstringminLength:
1maxLength:
80pattern:
^[a-z][a-z0-9_]+$detailOptionalstringminLength:
1maxLength:
2000instanceOptionalstringminLength:
1maxLength:
512errorsOptionalobject
Inspect JSON schema
{
"type": "object",
"additionalProperties": false,
"required": [
"type",
"title",
"status",
"code"
],
"properties": {
"type": {
"type": "string",
"format": "uri"
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"status": {
"type": "integer",
"minimum": 400,
"maximum": 599
},
"code": {
"type": "string",
"minLength": 1,
"maxLength": 80,
"pattern": "^[a-z][a-z0-9_]+$"
},
"detail": {
"type": "string",
"minLength": 1,
"maxLength": 2000
},
"instance": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"errors": {
"type": "object",
"additionalProperties": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 300
},
"minItems": 1,
"maxItems": 10
}
}
}
}422Validation failed
X-Request-Id · Opaque trace reference; never contains user data.
application/problem+json
typeRequiredstringformat:
urititleRequiredstringminLength:
1maxLength:
200statusRequiredintegerminimum:
400maximum:
599codeRequiredstringminLength:
1maxLength:
80pattern:
^[a-z][a-z0-9_]+$detailOptionalstringminLength:
1maxLength:
2000instanceOptionalstringminLength:
1maxLength:
512errorsOptionalobject
Inspect JSON schema
{
"type": "object",
"additionalProperties": false,
"required": [
"type",
"title",
"status",
"code"
],
"properties": {
"type": {
"type": "string",
"format": "uri"
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"status": {
"type": "integer",
"minimum": 400,
"maximum": 599
},
"code": {
"type": "string",
"minLength": 1,
"maxLength": 80,
"pattern": "^[a-z][a-z0-9_]+$"
},
"detail": {
"type": "string",
"minLength": 1,
"maxLength": 2000
},
"instance": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"errors": {
"type": "object",
"additionalProperties": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 300
},
"minItems": 1,
"maxItems": 10
}
}
}
}429Too many requests
X-Request-Id · Opaque trace reference; never contains user data.
Retry-After · Seconds before retry; do not repeat an unknown write automatically.
application/problem+json
typeRequiredstringformat:
urititleRequiredstringminLength:
1maxLength:
200statusRequiredintegerminimum:
400maximum:
599codeRequiredstringminLength:
1maxLength:
80pattern:
^[a-z][a-z0-9_]+$detailOptionalstringminLength:
1maxLength:
2000instanceOptionalstringminLength:
1maxLength:
512errorsOptionalobject
Inspect JSON schema
{
"type": "object",
"additionalProperties": false,
"required": [
"type",
"title",
"status",
"code"
],
"properties": {
"type": {
"type": "string",
"format": "uri"
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"status": {
"type": "integer",
"minimum": 400,
"maximum": 599
},
"code": {
"type": "string",
"minLength": 1,
"maxLength": 80,
"pattern": "^[a-z][a-z0-9_]+$"
},
"detail": {
"type": "string",
"minLength": 1,
"maxLength": 2000
},
"instance": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"errors": {
"type": "object",
"additionalProperties": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 300
},
"minItems": 1,
"maxItems": 10
}
}
}
}500Service failed
X-Request-Id · Opaque trace reference; never contains user data.
application/problem+json
typeRequiredstringformat:
urititleRequiredstringminLength:
1maxLength:
200statusRequiredintegerminimum:
400maximum:
599codeRequiredstringminLength:
1maxLength:
80pattern:
^[a-z][a-z0-9_]+$detailOptionalstringminLength:
1maxLength:
2000instanceOptionalstringminLength:
1maxLength:
512errorsOptionalobject
Inspect JSON schema
{
"type": "object",
"additionalProperties": false,
"required": [
"type",
"title",
"status",
"code"
],
"properties": {
"type": {
"type": "string",
"format": "uri"
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"status": {
"type": "integer",
"minimum": 400,
"maximum": 599
},
"code": {
"type": "string",
"minLength": 1,
"maxLength": 80,
"pattern": "^[a-z][a-z0-9_]+$"
},
"detail": {
"type": "string",
"minLength": 1,
"maxLength": 2000
},
"instance": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"errors": {
"type": "object",
"additionalProperties": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 300
},
"minItems": 1,
"maxItems": 10
}
}
}
}503Service unavailable
X-Request-Id · Opaque trace reference; never contains user data.
Retry-After · Seconds before retry; do not repeat an unknown write automatically.
application/problem+json
typeRequiredstringformat:
urititleRequiredstringminLength:
1maxLength:
200statusRequiredintegerminimum:
400maximum:
599codeRequiredstringminLength:
1maxLength:
80pattern:
^[a-z][a-z0-9_]+$detailOptionalstringminLength:
1maxLength:
2000instanceOptionalstringminLength:
1maxLength:
512errorsOptionalobject
Inspect JSON schema
{
"type": "object",
"additionalProperties": false,
"required": [
"type",
"title",
"status",
"code"
],
"properties": {
"type": {
"type": "string",
"format": "uri"
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"status": {
"type": "integer",
"minimum": 400,
"maximum": 599
},
"code": {
"type": "string",
"minLength": 1,
"maxLength": 80,
"pattern": "^[a-z][a-z0-9_]+$"
},
"detail": {
"type": "string",
"minLength": 1,
"maxLength": 2000
},
"instance": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"errors": {
"type": "object",
"additionalProperties": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 300
},
"minItems": 1,
"maxItems": 10
}
}
}
}