OrionIQ API

Agents configured with the API trigger run on demand when you call the OrionIQ API. Use it to start a run from a CI pipeline, an incident workflow, or any external system, then poll for the result.

To get an agent's ID and a ready-to-copy request for each endpoint, open the agent's actions menu in the Agents Hub and select API References.

Authentication

All requests must include the x-api-token header.

In the code blocks below:

• Replace <<API-TOKEN>> with an API token from the account that owns the agent
• Replace <<API-URL>> with your region's base API URL. For more information, see Account region.
• Replace <<AGENT-ID>> with the agent's ID

A request with a missing or invalid token returns 401.

Run an agent

POST /v2/ai-agent/<<AGENT-ID>>

Starts a new run and returns immediately with a session ID. The run itself is asynchronous — poll for the result with Get run status.

Sample request

curl -X POST \
  https://<<API-URL>>/v2/ai-agent/<<AGENT-ID>> \
  -H 'Content-Type: application/json' \
  -H 'X-API-TOKEN: <<API-TOKEN>>' \
  -d '{
    "context": {
      "message": "Summarize the errors in the checkout service",
      "additionalContext": "Deployment 4.12.0 rolled out at 09:00 UTC",
      "timerange": {
        "startTime": "2026-08-27T08:00:00Z",
        "endTime": "2026-08-27T10:00:00Z"
      }
    }
  }'

Field	Description
context.message	The prompt for this run.
context.additionalContext	Optional free-text context to pass to the agent.
context.timerange	Optional startTime and endTime bounding the data the agent analyzes.
context.security	Optional list of accounts to query, each with an optional filter of field and value.
integrations	Optional list of integration connections the run may use.

Fields you send override the matching fields in the agent's saved Payload (JSON).

Response

{
  "status": "started",
  "sessionId": "<session-id>"
}

A disabled agent returns 404, unless its trigger type is Alert. When OrionIQ is temporarily shut down for maintenance, the endpoint returns 503.

Get run status

GET /v2/ai-agent/<<AGENT-ID>>/<session-id>

Returns the current status of a run. Poll this endpoint until the status is terminal.

Sample request

curl -X GET \
  https://<<API-URL>>/v2/ai-agent/<<AGENT-ID>>/<session-id> \
  -H 'Content-Type: application/json' \
  -H 'X-API-TOKEN: <<API-TOKEN>>'

Response

{
  "status": "done",
  "message": "<agent-response>",
  "totalSteps": 12
}

Status	Meaning
loading	The run is still in progress. Keep polling.
done	The run finished. message holds the agent's output.
error	The run failed. message holds the reason.
canceled	The run was canceled.
timeout	The request timed out before the run produced new data. Poll again.

totalSteps reports how many steps the agent has produced so far.

Send a follow-up

POST /v2/ai-agent/<<AGENT-ID>>/<session-id>

Continues the same conversation. Allowed only after the previous turn reached a terminal status. The request body takes the same context object as Run an agent, and the response returns the same session ID, which you poll with Get run status.

{
  "status": "started",
  "sessionId": "<session-id>"
}

Enable or disable an agent

POST /v2/ai-agent/<<AGENT-ID>>/enable
POST /v2/ai-agent/<<AGENT-ID>>/disable

A disabled agent does not start new runs, whatever its trigger configuration.

Response

{
  "id": "<agent-id>",
  "active": true
}

Submit feedback

POST /v2/ai-agent/<<AGENT-ID>>/feedback

Rates one or more runs. Feedback appears in the Usage & Performance Dashboard.

Sample request

curl -X POST \
  https://<<API-URL>>/v2/ai-agent/<<AGENT-ID>>/feedback \
  -H 'Content-Type: application/json' \
  -H 'X-API-TOKEN: <<API-TOKEN>>' \
  -d '[
    {
      "sessionId": "<session-id>",
      "feedbackName": "run-quality",
      "score": 100,
      "comment": "Correctly identified the failing dependency."
    }
  ]'

Field	Description
sessionId	The run to rate.
feedbackName	A name identifying the kind of feedback.
score	A number, or a boolean that is converted to 100 for true and 0 for false.
comment	Optional free-text note. Omitting it leaves an existing comment unchanged.

A run holds one feedback record, so submitting again for the same session updates it.

Response

[
  {
    "id": "<feedback-id>",
    "createdAt": "<timestamp>",
    "agentId": "<agent-id>",
    "accountId": 12345,
    "sessionId": "<session-id>",
    "feedbackName": "run-quality",
    "score": 100,
    "comment": "Correctly identified the failing dependency."
  }
]

Get feedback

GET /v2/ai-agent/<<AGENT-ID>>/feedback/<session-id>

Returns the feedback record for a run, in the same shape as a single entry in the Submit feedback response. Returns 404 when the run has no feedback.

note

Agents don't have to be reachable over the API to be rated. Runs started by a Scheduled, Deployment, or Alert trigger can be rated from the Agents Hub, and the same feedback endpoints apply to them.