Ask agent

POST

https://api.sureshake.com/v2/entities/{entityId}/collections/{id}/agent/messages

Path parameters

entityId
string
required
format: uuid

id
string
required
format: uuid

Request body JSON required

message
string
required
maxLength: 4000 · minLength: 1
history
optional
array of
object
default: []
- role
  user
  or
  assistant
  required
- content
  string
  required
  maxLength: 8000 · minLength: 1
}
scope
optional
collection
or
subtree
default: "subtree"

Returns

200

Default Response

JSON

data
object
required
- answer
  string
  required
- citations
  array of
  object
  required
  label
  string
  required
  reportId
  string
  required
  format: uuid
  title
  string
  required
  truncated
  boolean
  required
  document
  optional
  read
  or
  too_large
  or
  over_limit
  or
  unsupported
  or
  unavailable
- sources
  array of
  object
  required
  label
  string
  required
  reportId
  string
  required
  format: uuid
  title
  string
  required
  truncated
  boolean
  required
  document
  optional
  read
  or
  too_large
  or
  over_limit
  or
  unsupported
  or
  unavailable
- excluded
  array of
  object
  required
  reportId
  string
  required
  format: uuid
  reason
  not_readable
  or
  over_limit
  required
}

400

Default Response

JSON

error
object
required
- code
  string
  required
  Machine-readable error code (e.g., NOT_FOUND)
- message
  string
  required
  Human-readable error message
- details
  optional
  unknown
  Optional structured error details
- traceId
  optional
  string
  Unique ID for log correlation
}

401

Default Response

JSON

error
object
required
- code
  string
  required
  Machine-readable error code (e.g., NOT_FOUND)
- message
  string
  required
  Human-readable error message
- details
  optional
  unknown
  Optional structured error details
- traceId
  optional
  string
  Unique ID for log correlation
}

403

Default Response

JSON

error
object
required
- code
  string
  required
  Machine-readable error code (e.g., NOT_FOUND)
- message
  string
  required
  Human-readable error message
- details
  optional
  unknown
  Optional structured error details
- traceId
  optional
  string
  Unique ID for log correlation
}

404

Default Response

JSON

error
object
required
- code
  string
  required
  Machine-readable error code (e.g., NOT_FOUND)
- message
  string
  required
  Human-readable error message
- details
  optional
  unknown
  Optional structured error details
- traceId
  optional
  string
  Unique ID for log correlation
}

409

Default Response

JSON

error
object
required
- code
  string
  required
  Machine-readable error code (e.g., NOT_FOUND)
- message
  string
  required
  Human-readable error message
- details
  optional
  unknown
  Optional structured error details
- traceId
  optional
  string
  Unique ID for log correlation
}

500

Default Response

JSON

error
object
required
- code
  string
  required
  Machine-readable error code (e.g., NOT_FOUND)
- message
  string
  required
  Human-readable error message
- details
  optional
  unknown
  Optional structured error details
- traceId
  optional
  string
  Unique ID for log correlation
}

503

Default Response

JSON

error
object
required
- code
  string
  required
  Machine-readable error code (e.g., NOT_FOUND)
- message
  string
  required
  Human-readable error message
- details
  optional
  unknown
  Optional structured error details
- traceId
  optional
  string
  Unique ID for log correlation
}

curl --request POST \ --url 'https://api.sureshake.com/v2/entities/<entityId>/collections/<id>/agent/messages' \ --header 'Content-Type: application/json' \ --data ' { "message": "string", "history": [], "scope": "collection" } '

{ "data": { "answer": "string", "citations": [ { "label": "string", "reportId": "836df459-dc40-4aa1-972a-6eb0a864dff9", "title": "string", "truncated": true, "document": "read" } ], "sources": [ { "label": "string", "reportId": "836df459-dc40-4aa1-972a-6eb0a864dff9", "title": "string", "truncated": true, "document": "read" } ], "excluded": [ { "reportId": "836df459-dc40-4aa1-972a-6eb0a864dff9", "reason": "not_readable" } ] } }