Skip to content
Workshape Catalyst Operator Docs

Conversations

List the caller’s conversations in a workspace

Section titled “List the caller’s conversations in a workspace”

GET /api/v1/conversations

Operation
conversations.list
Accepts
sessionCookie, sessionToken
Scope
conversation:read
Effect
reading
Rate class
read

Parameters

  • limit integer in query, optional, default 50, minimum 1, maximum 200
  • cursor string in query, optional, minLength 1
  • collaborationWorkspaceId string in query, optional
  • query string in query, optional, minLength 1, maxLength 200

Answers

  • 200 One page of the list

    application/json: object

  • 400 BAD_REQUEST: The request cannot be read.
  • 401 UNAUTHENTICATED: No credential was presented, or the credential is not valid.
  • 403 FORBIDDEN: The caller lacks the scope or the right this operation requires.
  • 404 NOT_FOUND: The resource does not exist, is not visible to the caller, or the instance runs without this operation.
  • 422 VALIDATION_FAILED: Path, query or body do not match the operation's schema.
  • 429 RATE_LIMITED: The caller sent too many requests of this operation's rate class. details.retryAfterSeconds and the Retry-After header give the seconds to wait. The numbers are the instance's, set under rateLimits in its release config.
  • 500 INTERNAL: The instance failed. The message never carries details.

Create an empty conversation

Section titled “Create an empty conversation”

POST /api/v1/conversations

Operation
conversations.create
Accepts
sessionCookie, sessionToken
Scope
conversation:write
Effect
changing
Rate class
write

Request body

application/json: CreateConversationRequest

Answers

  • 200 The result

    application/json: Conversation

  • 400 BAD_REQUEST: The request cannot be read.
  • 401 UNAUTHENTICATED: No credential was presented, or the credential is not valid.
  • 403 FORBIDDEN: The caller lacks the scope or the right this operation requires.
  • 404 NOT_FOUND: The resource does not exist, is not visible to the caller, or the instance runs without this operation.
  • 422 VALIDATION_FAILED: Path, query or body do not match the operation's schema.
  • 429 RATE_LIMITED: The caller sent too many requests of this operation's rate class. details.retryAfterSeconds and the Retry-After header give the seconds to wait. The numbers are the instance's, set under rateLimits in its release config.
  • 500 INTERNAL: The instance failed. The message never carries details.

Create a conversation and start its first agent run

Section titled “Create a conversation and start its first agent run”

POST /api/v1/conversations/runs

Operation
conversations.runs.create
Accepts
sessionCookie, sessionToken
Scope
conversation:write
Effect
changing
Rate class
write

Request body

application/json: CreateConversationRunRequest

Answers

  • 200 The result

    application/json: StartConversationRunResponse

  • 400 BAD_REQUEST: The request cannot be read.
  • 401 UNAUTHENTICATED: No credential was presented, or the credential is not valid.
  • 403 FORBIDDEN: The caller lacks the scope or the right this operation requires.
  • 404 NOT_FOUND: The resource does not exist, is not visible to the caller, or the instance runs without this operation.
  • 409 CONFLICT: The request conflicts with the current state of the resource.
  • 422 VALIDATION_FAILED: Path, query or body do not match the operation's schema.
  • 429 RATE_LIMITED: The caller sent too many requests of this operation's rate class. details.retryAfterSeconds and the Retry-After header give the seconds to wait. The numbers are the instance's, set under rateLimits in its release config.
  • 500 INTERNAL: The instance failed. The message never carries details.

Delete a conversation

Section titled “Delete a conversation”

DELETE /api/v1/conversations/{conversationId}

Operation
conversations.delete
Accepts
sessionCookie, sessionToken
Scope
conversation:write
Effect
changing
Rate class
write

Parameters

  • conversationId string in path, required

Answers

  • 200 The result

    application/json: Conversation

  • 400 BAD_REQUEST: The request cannot be read.
  • 401 UNAUTHENTICATED: No credential was presented, or the credential is not valid.
  • 403 FORBIDDEN: The caller lacks the scope or the right this operation requires.
  • 404 NOT_FOUND: The resource does not exist, is not visible to the caller, or the instance runs without this operation.
  • 409 CONFLICT: The request conflicts with the current state of the resource.
  • 422 VALIDATION_FAILED: Path, query or body do not match the operation's schema.
  • 429 RATE_LIMITED: The caller sent too many requests of this operation's rate class. details.retryAfterSeconds and the Retry-After header give the seconds to wait. The numbers are the instance's, set under rateLimits in its release config.
  • 500 INTERNAL: The instance failed. The message never carries details.

List the messages of a conversation

Section titled “List the messages of a conversation”

GET /api/v1/conversations/{conversationId}/messages

Operation
conversations.messages.list
Accepts
sessionCookie, sessionToken
Scope
conversation:read
Effect
reading
Rate class
read

Parameters

  • conversationId string in path, required
  • limit integer in query, optional, default 50, minimum 1, maximum 200
  • cursor string in query, optional, minLength 1

Answers

  • 200 One page of the list

    application/json: object

    • items array of Message required
    • nextCursor string optional
  • 400 BAD_REQUEST: The request cannot be read.
  • 401 UNAUTHENTICATED: No credential was presented, or the credential is not valid.
  • 403 FORBIDDEN: The caller lacks the scope or the right this operation requires.
  • 404 NOT_FOUND: The resource does not exist, is not visible to the caller, or the instance runs without this operation.
  • 422 VALIDATION_FAILED: Path, query or body do not match the operation's schema.
  • 429 RATE_LIMITED: The caller sent too many requests of this operation's rate class. details.retryAfterSeconds and the Retry-After header give the seconds to wait. The numbers are the instance's, set under rateLimits in its release config.
  • 500 INTERNAL: The instance failed. The message never carries details.

Move a conversation to another workspace or visibility

Section titled “Move a conversation to another workspace or visibility”

POST /api/v1/conversations/{conversationId}/move

Operation
conversations.move
Accepts
sessionCookie, sessionToken
Scope
conversation:write
Effect
changing
Rate class
write

Parameters

  • conversationId string in path, required

Request body

application/json: MoveConversationRequest

Answers

  • 200 The result

    application/json: Conversation

  • 400 BAD_REQUEST: The request cannot be read.
  • 401 UNAUTHENTICATED: No credential was presented, or the credential is not valid.
  • 403 FORBIDDEN: The caller lacks the scope or the right this operation requires.
  • 404 NOT_FOUND: The resource does not exist, is not visible to the caller, or the instance runs without this operation.
  • 409 CONFLICT: The request conflicts with the current state of the resource.
  • 422 VALIDATION_FAILED: Path, query or body do not match the operation's schema.
  • 429 RATE_LIMITED: The caller sent too many requests of this operation's rate class. details.retryAfterSeconds and the Retry-After header give the seconds to wait. The numbers are the instance's, set under rateLimits in its release config.
  • 500 INTERNAL: The instance failed. The message never carries details.

List the files and data a conversation produced

Section titled “List the files and data a conversation produced”

GET /api/v1/conversations/{conversationId}/resources

Operation
conversations.resources.list
Accepts
sessionCookie, sessionToken
Scope
conversation:read
Effect
reading
Rate class
read

Parameters

  • conversationId string in path, required
  • limit integer in query, optional, default 50, minimum 1, maximum 200
  • cursor string in query, optional, minLength 1

Answers

  • 200 One page of the list

    application/json: object

  • 400 BAD_REQUEST: The request cannot be read.
  • 401 UNAUTHENTICATED: No credential was presented, or the credential is not valid.
  • 403 FORBIDDEN: The caller lacks the scope or the right this operation requires.
  • 404 NOT_FOUND: The resource does not exist, is not visible to the caller, or the instance runs without this operation.
  • 422 VALIDATION_FAILED: Path, query or body do not match the operation's schema.
  • 429 RATE_LIMITED: The caller sent too many requests of this operation's rate class. details.retryAfterSeconds and the Retry-After header give the seconds to wait. The numbers are the instance's, set under rateLimits in its release config.
  • 500 INTERNAL: The instance failed. The message never carries details.

Send a message and start an agent run

Section titled “Send a message and start an agent run”

POST /api/v1/conversations/{conversationId}/runs

Operation
conversations.runs.start
Accepts
sessionCookie, sessionToken
Scope
conversation:write
Effect
changing
Rate class
write

Parameters

  • conversationId string in path, required

Request body

application/json: StartConversationRunRequest

Answers

  • 200 The result

    application/json: StartConversationRunResponse

  • 400 BAD_REQUEST: The request cannot be read.
  • 401 UNAUTHENTICATED: No credential was presented, or the credential is not valid.
  • 403 FORBIDDEN: The caller lacks the scope or the right this operation requires.
  • 404 NOT_FOUND: The resource does not exist, is not visible to the caller, or the instance runs without this operation.
  • 409 CONFLICT: The request conflicts with the current state of the resource.
  • 422 VALIDATION_FAILED: Path, query or body do not match the operation's schema.
  • 429 RATE_LIMITED: The caller sent too many requests of this operation's rate class. details.retryAfterSeconds and the Retry-After header give the seconds to wait. The numbers are the instance's, set under rateLimits in its release config.
  • 500 INTERNAL: The instance failed. The message never carries details.

Cancel an agent run

Section titled “Cancel an agent run”

POST /api/v1/conversations/{conversationId}/runs/{runId}/cancel

Operation
conversations.runs.cancel
Accepts
sessionCookie, sessionToken
Scope
run:cancel
Effect
changing
Rate class
write

Parameters

  • conversationId string in path, required
  • runId string in path, required

Request body

application/json: CancelRunRequest

Answers

  • 200 The result

    application/json: CancelRunResponse

  • 400 BAD_REQUEST: The request cannot be read.
  • 401 UNAUTHENTICATED: No credential was presented, or the credential is not valid.
  • 403 FORBIDDEN: The caller lacks the scope or the right this operation requires.
  • 404 NOT_FOUND: The resource does not exist, is not visible to the caller, or the instance runs without this operation.
  • 422 VALIDATION_FAILED: Path, query or body do not match the operation's schema.
  • 429 RATE_LIMITED: The caller sent too many requests of this operation's rate class. details.retryAfterSeconds and the Retry-After header give the seconds to wait. The numbers are the instance's, set under rateLimits in its release config.
  • 500 INTERNAL: The instance failed. The message never carries details.

Continue a waiting agent run or decide its tool permission

Section titled “Continue a waiting agent run or decide its tool permission”

POST /api/v1/conversations/{conversationId}/runs/{runId}/commands

Operation
conversations.runs.command
Accepts
sessionCookie, sessionToken
Scope
run:command
Effect
changing
Rate class
write

Parameters

  • conversationId string in path, required
  • runId string in path, required

Request body

application/json: RunCommandRequest

Answers

  • 200 The result

    application/json: RunCommandResponse

  • 400 BAD_REQUEST: The request cannot be read.
  • 401 UNAUTHENTICATED: No credential was presented, or the credential is not valid.
  • 403 FORBIDDEN: The caller lacks the scope or the right this operation requires.
  • 404 NOT_FOUND: The resource does not exist, is not visible to the caller, or the instance runs without this operation.
  • 409 CONFLICT: The request conflicts with the current state of the resource.
  • 422 VALIDATION_FAILED: Path, query or body do not match the operation's schema.
  • 429 RATE_LIMITED: The caller sent too many requests of this operation's rate class. details.retryAfterSeconds and the Retry-After header give the seconds to wait. The numbers are the instance's, set under rateLimits in its release config.
  • 500 INTERNAL: The instance failed. The message never carries details.

Follow the events of an agent run

Section titled “Follow the events of an agent run”

GET /api/v1/conversations/{conversationId}/runs/{runId}/events

Operation
conversations.runs.observe
Accepts
sessionCookie, sessionToken
Scope
run:observe
Effect
reading
Rate class
read

Parameters

  • conversationId string in path, required
  • runId string in path, required
  • after string in query, optional

Answers

  • 200 A stream of server-sent events. The data of every event is one JSON value of the schema; id is the position to resume from.

    text/event-stream: RunObservation

  • 204 The stream has ended and holds no event after the position asked for
  • 400 BAD_REQUEST: The request cannot be read.
  • 401 UNAUTHENTICATED: No credential was presented, or the credential is not valid.
  • 403 FORBIDDEN: The caller lacks the scope or the right this operation requires.
  • 404 NOT_FOUND: The resource does not exist, is not visible to the caller, or the instance runs without this operation.
  • 422 VALIDATION_FAILED: Path, query or body do not match the operation's schema.
  • 429 RATE_LIMITED: The caller sent too many requests of this operation's rate class. details.retryAfterSeconds and the Retry-After header give the seconds to wait. The numbers are the instance's, set under rateLimits in its release config.
  • 500 INTERNAL: The instance failed. The message never carries details.

Read one structured data resource of a conversation

Section titled “Read one structured data resource of a conversation”

GET /api/v1/conversations/{conversationId}/structured-data/{structuredDataResourceId}

Operation
conversations.structured_data.get
Accepts
sessionCookie, sessionToken
Scope
conversation:read
Effect
reading
Rate class
read

Parameters

  • conversationId string in path, required
  • structuredDataResourceId string in path, required

Answers

  • 200 The result

    application/json: StructuredDataResourceResponse

  • 400 BAD_REQUEST: The request cannot be read.
  • 401 UNAUTHENTICATED: No credential was presented, or the credential is not valid.
  • 403 FORBIDDEN: The caller lacks the scope or the right this operation requires.
  • 404 NOT_FOUND: The resource does not exist, is not visible to the caller, or the instance runs without this operation.
  • 422 VALIDATION_FAILED: Path, query or body do not match the operation's schema.
  • 429 RATE_LIMITED: The caller sent too many requests of this operation's rate class. details.retryAfterSeconds and the Retry-After header give the seconds to wait. The numbers are the instance's, set under rateLimits in its release config.
  • 500 INTERNAL: The instance failed. The message never carries details.

Read a conversation with its messages and active run

Section titled “Read a conversation with its messages and active run”

GET /api/v1/conversations/{conversationId}/thread

Operation
conversations.thread.get
Accepts
sessionCookie, sessionToken
Scope
conversation:read
Effect
reading
Rate class
read

Parameters

  • conversationId string in path, required

Answers

  • 200 The result

    application/json: ConversationThreadSnapshot

  • 400 BAD_REQUEST: The request cannot be read.
  • 401 UNAUTHENTICATED: No credential was presented, or the credential is not valid.
  • 403 FORBIDDEN: The caller lacks the scope or the right this operation requires.
  • 404 NOT_FOUND: The resource does not exist, is not visible to the caller, or the instance runs without this operation.
  • 422 VALIDATION_FAILED: Path, query or body do not match the operation's schema.
  • 429 RATE_LIMITED: The caller sent too many requests of this operation's rate class. details.retryAfterSeconds and the Retry-After header give the seconds to wait. The numbers are the instance's, set under rateLimits in its release config.
  • 500 INTERNAL: The instance failed. The message never carries details.

Rename a conversation

Section titled “Rename a conversation”

PATCH /api/v1/conversations/{conversationId}/title

Operation
conversations.rename
Accepts
sessionCookie, sessionToken
Scope
conversation:write
Effect
changing
Rate class
write

Parameters

  • conversationId string in path, required

Request body

application/json: RenameConversationRequest

Answers

  • 200 The result

    application/json: Conversation

  • 400 BAD_REQUEST: The request cannot be read.
  • 401 UNAUTHENTICATED: No credential was presented, or the credential is not valid.
  • 403 FORBIDDEN: The caller lacks the scope or the right this operation requires.
  • 404 NOT_FOUND: The resource does not exist, is not visible to the caller, or the instance runs without this operation.
  • 422 VALIDATION_FAILED: Path, query or body do not match the operation's schema.
  • 429 RATE_LIMITED: The caller sent too many requests of this operation's rate class. details.retryAfterSeconds and the Retry-After header give the seconds to wait. The numbers are the instance's, set under rateLimits in its release config.
  • 500 INTERNAL: The instance failed. The message never carries details.