Skip to main content
POST
Requires version 2.0.1 or later of the Archetype platform.

Overview

This endpoint sends one request payload to the agent of a serving session’s deployment and returns its answer. The body is whatever the blueprint’s source connector accepts, and response is whatever its sink produces. Both shapes belong to the blueprint, not to this API. The session must be running. After Create Session, poll Get Session until it is. Anyone who can see the session’s project can query it.

Request

string
required
Session ses_ id.
object
required
Whatever the agent’s source connector accepts, as JSON. The shape belongs to the blueprint, not to this endpoint.

Response

string
required
Whether the query produced an answer. Always completed in a 200 response: a query that fails returns an error status instead.
object
required
The agent’s answer, passed through as it came back.
number
required
Total server-side time, in milliseconds.

Important Notes

  • A 400 means the body is not JSON or is larger than the service accepts (invalid_request_body), or the agent rejected the payload, with its reason in the message. Resending the same body will not succeed.
  • A 404 means the session does not exist, belongs to another organization, or is in a project you cannot see.
  • A 409 with the code session_not_running means the session has ended, including because its deployment stopped or failed. Open a new session. A 409 with the code conflict means the session is a batch session or the deployment’s agent has stopped. The message says why where that is known, and resending will not succeed.
  • A 429 means the agent is already answering as many queries at once as it will. Retry with backoff after the number of seconds in the Retry-After header.
  • A 500 with the code agent_failed means the agent processed the query and failed it, with its reason in the message. The same request produces the same answer, so do not retry it.
  • A 503 means the agent could not be reached or did not answer in time (unavailable), or the service is already answering as many queries as it will (node_at_capacity, with a Retry-After header). Retry.
  • A 504 with the code query_timeout means the agent’s time budget ran out before it had an answer. The budget includes time spent waiting behind other queries to the same deployment, from this session or another. Send less data per query, or fewer queries at once.