Chats · Oblive Docs

List chats

GET/organizations/{organizationId}/chats

Path Parameters

organizationId*string

Organization identifier.

Formatuuid

Query Parameters

cursor?string

Opaque cursor returned by the previous page.

limit?integer

sortBy?string

Value in

"id"
"title"
"status"
"lastMessageAt"
"createdAt"
"updatedAt"

sortDirection?string

Value in

"asc"
"desc"

status?string

Value in

"open"
"archived"

isOnboardingChat?boolean

q?string

Case-insensitive search across chat titles and visible message content.

`application/json`

curl -X GET "https://example.com/organizations/497f6eca-6276-4993-bfeb-53cbbbba6f08/chats"

{  "success": true,  "statusCode": 200,  "message": "Chats listed.",  "data": [    {      "id": "0ce65ee0-dcd9-46c2-90a4-243f5d54dc66",      "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1",      "title": "Customer Escalation",      "status": "open",      "summary": null,      "harnessSessionId": null,      "settings": {        "pinnedTaskIds": []      },      "lastMessageAt": "2026-01-01T00:00:00.000Z",      "archivedAt": null,      "createdAt": "2026-01-01T00:00:00.000Z",      "updatedAt": "2026-01-01T00:00:00.000Z",      "isOnboardingChat": false    }  ],  "pagination": {    "cursor": null,    "limit": 50,    "nextCursor": null,    "previousCursor": null,    "hasNextPage": false,    "hasPreviousPage": false  },  "meta": {    "timestamp": "2026-01-01T00:00:00.000Z"  }}

{  "success": false,  "statusCode": 400,  "message": "Validation failed.",  "error": {    "code": "validation_failed",    "issues": [      {        "path": "organizationId",        "message": "Must be a valid UUID.",        "code": "invalid_format"      }    ]  },  "meta": {    "timestamp": "2026-01-01T00:00:00.000Z"  }}

Create chat

POST/organizations/{organizationId}/chats

Path Parameters

organizationId*string

Organization identifier.

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

`application/json`

curl -X POST "https://example.com/organizations/497f6eca-6276-4993-bfeb-53cbbbba6f08/chats" \  -H "Content-Type: application/json" \  -d '{    "title": "Customer Escalation"  }'

{  "success": true,  "statusCode": 201,  "message": "Chat created.",  "data": {    "id": "0ce65ee0-dcd9-46c2-90a4-243f5d54dc66",    "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1",    "title": "Customer Escalation",    "status": "open",    "summary": null,    "harnessSessionId": null,    "settings": {      "pinnedTaskIds": []    },    "lastMessageAt": "2026-01-01T00:00:00.000Z",    "archivedAt": null,    "createdAt": "2026-01-01T00:00:00.000Z",    "updatedAt": "2026-01-01T00:00:00.000Z",    "isOnboardingChat": false  },  "meta": {    "timestamp": "2026-01-01T00:00:00.000Z"  }}

{  "success": false,  "statusCode": 400,  "message": "Validation failed.",  "error": {    "code": "validation_failed",    "issues": [      {        "path": "organizationId",        "message": "Must be a valid UUID.",        "code": "invalid_format"      }    ]  },  "meta": {    "timestamp": "2026-01-01T00:00:00.000Z"  }}

Get chat

GET/organizations/{organizationId}/chats/{id}

Path Parameters

organizationId*string

Organization identifier.

Formatuuid

id*string

Resource identifier.

Formatuuid

`application/json`

curl -X GET "https://example.com/organizations/497f6eca-6276-4993-bfeb-53cbbbba6f08/chats/497f6eca-6276-4993-bfeb-53cbbbba6f08"

{  "success": true,  "statusCode": 200,  "message": "Chat found.",  "data": {    "id": "0ce65ee0-dcd9-46c2-90a4-243f5d54dc66",    "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1",    "title": "Customer Escalation",    "status": "open",    "summary": null,    "harnessSessionId": null,    "settings": {      "pinnedTaskIds": []    },    "lastMessageAt": "2026-01-01T00:00:00.000Z",    "archivedAt": null,    "createdAt": "2026-01-01T00:00:00.000Z",    "updatedAt": "2026-01-01T00:00:00.000Z",    "isOnboardingChat": false  },  "meta": {    "timestamp": "2026-01-01T00:00:00.000Z"  }}

{  "success": false,  "statusCode": 400,  "message": "Validation failed.",  "error": {    "code": "validation_failed",    "issues": [      {        "path": "organizationId",        "message": "Must be a valid UUID.",        "code": "invalid_format"      }    ]  },  "meta": {    "timestamp": "2026-01-01T00:00:00.000Z"  }}

{  "success": false,  "statusCode": 404,  "message": "Chat not found.",  "error": {    "code": "chat_not_found"  },  "meta": {    "timestamp": "2026-01-01T00:00:00.000Z"  }}

Update chat

PATCH/organizations/{organizationId}/chats/{id}

Path Parameters

organizationId*string

Organization identifier.

Formatuuid

id*string

Resource identifier.

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

`application/json`

curl -X PATCH "https://example.com/organizations/497f6eca-6276-4993-bfeb-53cbbbba6f08/chats/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Content-Type: application/json" \  -d '{    "title": "Customer Escalation"  }'

{  "success": true,  "statusCode": 200,  "message": "Chat updated.",  "data": {    "id": "0ce65ee0-dcd9-46c2-90a4-243f5d54dc66",    "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1",    "title": "Customer Escalation",    "status": "open",    "summary": null,    "harnessSessionId": null,    "settings": {      "pinnedTaskIds": []    },    "lastMessageAt": "2026-01-01T00:00:00.000Z",    "archivedAt": null,    "createdAt": "2026-01-01T00:00:00.000Z",    "updatedAt": "2026-01-01T00:00:00.000Z",    "isOnboardingChat": false  },  "meta": {    "timestamp": "2026-01-01T00:00:00.000Z"  }}

{  "success": false,  "statusCode": 400,  "message": "Validation failed.",  "error": {    "code": "validation_failed",    "issues": [      {        "path": "organizationId",        "message": "Must be a valid UUID.",        "code": "invalid_format"      }    ]  },  "meta": {    "timestamp": "2026-01-01T00:00:00.000Z"  }}

{  "success": false,  "statusCode": 404,  "message": "Chat not found.",  "error": {    "code": "chat_not_found"  },  "meta": {    "timestamp": "2026-01-01T00:00:00.000Z"  }}

{  "success": false,  "statusCode": 409,  "message": "Wait for the active assistant response to finish before archiving this chat.",  "error": {    "code": "chat_response_active"  },  "meta": {    "timestamp": "2026-01-01T00:00:00.000Z"  }}

Delete chat

DELETE/organizations/{organizationId}/chats/{id}

Path Parameters

organizationId*string

Organization identifier.

Formatuuid

id*string

Resource identifier.

Formatuuid

`application/json`

curl -X DELETE "https://example.com/organizations/497f6eca-6276-4993-bfeb-53cbbbba6f08/chats/497f6eca-6276-4993-bfeb-53cbbbba6f08"

{  "success": true,  "statusCode": 200,  "message": "Chat deleted.",  "data": {    "id": "0ce65ee0-dcd9-46c2-90a4-243f5d54dc66",    "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1",    "title": "Customer Escalation",    "status": "open",    "summary": null,    "harnessSessionId": null,    "settings": {      "pinnedTaskIds": []    },    "lastMessageAt": "2026-01-01T00:00:00.000Z",    "archivedAt": null,    "createdAt": "2026-01-01T00:00:00.000Z",    "updatedAt": "2026-01-01T00:00:00.000Z",    "isOnboardingChat": false  },  "meta": {    "timestamp": "2026-01-01T00:00:00.000Z"  }}

{  "success": false,  "statusCode": 400,  "message": "Validation failed.",  "error": {    "code": "validation_failed",    "issues": [      {        "path": "organizationId",        "message": "Must be a valid UUID.",        "code": "invalid_format"      }    ]  },  "meta": {    "timestamp": "2026-01-01T00:00:00.000Z"  }}

{  "success": false,  "statusCode": 404,  "message": "Chat not found.",  "error": {    "code": "chat_not_found"  },  "meta": {    "timestamp": "2026-01-01T00:00:00.000Z"  }}

{  "success": false,  "statusCode": 409,  "message": "The organization onboarding chat cannot be changed.",  "error": {    "code": "onboarding_chat_immutable"  },  "meta": {    "timestamp": "2026-01-01T00:00:00.000Z"  }}

Stream chat events

GET/organizations/{organizationId}/chats/{chatId}/events

Starts with the latest persisted assistant snapshot, then streams revisioned message updates.

Path Parameters

organizationId*string

Organization identifier.

Formatuuid

chatId*string

Chat identifier.

Formatuuid

Header Parameters

Last-Event-ID?string

Last processed event in assistantMessageId:revision format.

`text/event-stream`

curl -X GET "https://example.com/organizations/497f6eca-6276-4993-bfeb-53cbbbba6f08/chats/497f6eca-6276-4993-bfeb-53cbbbba6f08/events" \  -H "Last-Event-ID: d4ad2b33-d18c-45c2-965d-22a883af9d89:4"

"id: d4ad2b33-d18c-45c2-965d-22a883af9d89:4\nevent: chat.snapshot\ndata: {\"type\":\"chat.snapshot\"}\n\n"

Cancel assistant response

POST/organizations/{organizationId}/chats/{chatId}/messages/{messageId}/cancel

Path Parameters

organizationId*string

Organization identifier.

Formatuuid

chatId*string

Chat identifier.

Formatuuid

messageId*string

Assistant message identifier.

Formatuuid

`application/json`

curl -X POST "https://example.com/organizations/497f6eca-6276-4993-bfeb-53cbbbba6f08/chats/497f6eca-6276-4993-bfeb-53cbbbba6f08/messages/497f6eca-6276-4993-bfeb-53cbbbba6f08/cancel"

{  "success": true,  "statusCode": 200,  "message": "Message cancellation requested.",  "data": {    "id": "380c8d1f-7a6a-4a8d-8dd9-3e9ecda3f4f1",    "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1",    "chatId": "0ce65ee0-dcd9-46c2-90a4-243f5d54dc66",    "replyToMessageId": null,    "role": "assistant",    "status": "cancelling",    "revision": 1,    "author": {      "kind": "human",      "displayName": "Operator"    },    "parts": [      {        "id": "part-1",        "kind": "text",        "text": "Create the onboarding plan."      }    ],    "error": null,    "completedAt": "2026-01-01T00:00:00.000Z",    "createdAt": "2026-01-01T00:00:00.000Z",    "updatedAt": "2026-01-01T00:00:00.000Z"  },  "meta": {    "timestamp": "2026-01-01T00:00:00.000Z"  }}

{  "success": false,  "statusCode": 404,  "message": "Assistant message not found.",  "error": {    "code": "message_not_found"  },  "meta": {    "timestamp": "2026-01-01T00:00:00.000Z"  }}

{  "success": false,  "statusCode": 409,  "message": "Assistant message cannot be cancelled from its current state.",  "error": {    "code": "message_not_cancellable"  },  "meta": {    "timestamp": "2026-01-01T00:00:00.000Z"  }}

Upload a chat attachment

PUT/organizations/{organizationId}/chats/{chatId}/attachments/{attachmentId}

Stores one validated Markdown, text/data, PDF, or raster-image file up to 50 MB under a client-generated, chat-scoped identifier. Supported extensions: .md, .markdown, .txt, .csv, .json, .yaml, .yml, .toml, .pdf, .png, .jpg, .jpeg, .webp, .gif. The backend derives the canonical media type, validates UTF-8 or the file signature, and rejects caller MIME disagreement.

Path Parameters

organizationId*string

Organization identifier.

Formatuuid

chatId*string

Chat identifier.

Formatuuid

attachmentId*string

Client-generated attachment identifier.

Formatuuid

Query Parameters

fileName*string

File name ending in .md, .markdown, .txt, .csv, .json, .yaml, .yml, .toml, .pdf, .png, .jpg, .jpeg, .webp, .gif.

mediaType*string

Canonical media type matching the validated file extension and bytes.

Value in

"text/markdown"
"text/plain"
"text/csv"
"application/json"
"application/yaml"
"application/toml"
"application/pdf"
"image/png"
"image/jpeg"
"image/webp"
"image/gif"

Request Body

application/octet-stream

TypeScript Definitions

Use the request body type in TypeScript.

body*file

Formatbinary

Response Body

`application/json`

curl -X PUT "https://example.com/organizations/497f6eca-6276-4993-bfeb-53cbbbba6f08/chats/497f6eca-6276-4993-bfeb-53cbbbba6f08/attachments/497f6eca-6276-4993-bfeb-53cbbbba6f08?fileName=string&mediaType=text%2Fmarkdown" \  -H "Content-Type: application/octet-stream" \  -d 'string'

{  "success": true,  "statusCode": 201,  "message": "Chat attachment stored.",  "data": {    "version": 1,    "id": "31d22752-e70d-42ce-a28a-39dc87dc8fc8",    "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1",    "chatId": "0ce65ee0-dcd9-46c2-90a4-243f5d54dc66",    "fileName": "project-brief.md",    "mediaType": "text/markdown",    "sizeBytes": 2048,    "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",    "createdAt": "2026-07-15T09:00:00.000Z",    "uri": "oblive://organizations/7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1/chats/0ce65ee0-dcd9-46c2-90a4-243f5d54dc66/attachments/31d22752-e70d-42ce-a28a-39dc87dc8fc8"  },  "meta": {    "timestamp": "2026-07-15T09:00:00.000Z"  }}

{  "success": false,  "statusCode": 400,  "message": "Validation failed.",  "error": {    "code": "validation_failed",    "issues": [      {        "path": "organizationId",        "message": "Must be a valid UUID.",        "code": "invalid_format"      }    ]  },  "meta": {    "timestamp": "2026-01-01T00:00:00.000Z"  }}

{  "success": false,  "statusCode": 409,  "message": "Attachments can only be added to open, non-onboarding chats.",  "error": {    "code": "attachment_not_allowed"  },  "meta": {    "timestamp": "2026-07-15T09:00:00.000Z"  }}

{  "success": false,  "statusCode": 413,  "message": "Attachments cannot exceed 50 MB.",  "error": {    "code": "attachment_invalid"  },  "meta": {    "timestamp": "2026-07-15T09:00:00.000Z"  }}

Read chat attachment bytes

GET/organizations/{organizationId}/chats/{chatId}/attachments/{attachmentId}/content

Path Parameters

organizationId*string

Organization identifier.

Formatuuid

chatId*string

Chat identifier.

Formatuuid

attachmentId*string

Client-generated attachment identifier.

Formatuuid

Query Parameters

disposition?string

Value in

"inline"
"attachment"

Header Parameters

Range?string

Response Body

`application/octet-stream`

`application/json`

curl -X GET "https://example.com/organizations/497f6eca-6276-4993-bfeb-53cbbbba6f08/chats/497f6eca-6276-4993-bfeb-53cbbbba6f08/attachments/497f6eca-6276-4993-bfeb-53cbbbba6f08/content"

"string"

"string"

{  "success": false,  "statusCode": 404,  "message": "Chat attachment not found.",  "error": {    "code": "attachment_not_found"  },  "meta": {    "timestamp": "2026-07-15T09:00:00.000Z"  }}

{  "success": false,  "statusCode": 416,  "message": "Requested byte range is not satisfiable.",  "error": {    "code": "range_not_satisfiable"  },  "meta": {    "timestamp": "2026-07-15T09:00:00.000Z"  }}

Read chat attachment metadata

HEAD/organizations/{organizationId}/chats/{chatId}/attachments/{attachmentId}/content

Path Parameters

organizationId*string

Organization identifier.

Formatuuid

chatId*string

Chat identifier.

Formatuuid

attachmentId*string

Client-generated attachment identifier.

Formatuuid

Query Parameters

disposition?string

Value in

"inline"
"attachment"

Header Parameters

Range?string

Response Body

`application/octet-stream`

`application/json`

curl -X HEAD "https://example.com/organizations/497f6eca-6276-4993-bfeb-53cbbbba6f08/chats/497f6eca-6276-4993-bfeb-53cbbbba6f08/attachments/497f6eca-6276-4993-bfeb-53cbbbba6f08/content"

"string"

"string"

{  "success": false,  "statusCode": 404,  "message": "Chat attachment not found.",  "error": {    "code": "attachment_not_found"  },  "meta": {    "timestamp": "2026-07-15T09:00:00.000Z"  }}

{  "success": false,  "statusCode": 416,  "message": "Requested byte range is not satisfiable.",  "error": {    "code": "range_not_satisfiable"  },  "meta": {    "timestamp": "2026-07-15T09:00:00.000Z"  }}

200application/json

400application/json

201application/json

400application/json

200application/json

400application/json

404application/json

200application/json

400application/json

404application/json

409application/json

200application/json

400application/json

404application/json

409application/json

200text/event-stream

200application/json

404application/json

409application/json

201application/json

400application/json

409application/json

413application/json

200application/octet-stream

206application/octet-stream

404application/json

416application/json

200application/octet-stream

206application/octet-stream

404application/json

416application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`text/event-stream`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/octet-stream`

`application/octet-stream`

`application/json`

`application/json`

`application/octet-stream`

`application/octet-stream`

`application/json`

`application/json`