Skip to main content

API

Beyond Studio, agents can be triggered and followed over HTTP. This page covers what matters to whoever integrates.

Two ways to authenticate​

FormFor whatHow
Imaginne sessionScripts acting as a personThe same Imaginne session, in the authorization header
Address credentialSystems triggering one specific agentThe credential generated when creating the HTTP address

There is no separate Agents signup or login. Whoever signs in to Imaginne is in.

The address credential is the right option for integration: it applies to one agent, has its own limits, and gives no access to Studio.

Triggering through an HTTP address​

Call the address you created, with the credential and a body in the format the agent declares.

The response is immediate and is not the result:

{
  "execution_id": "exec_…",
  "status": "queued",
  "status_url": "…"
}

The flow never runs inside the request. An automation waiting for a human approval would not fit inside an HTTP response time.

Validated input​

Triggering through an address validates the input against what the agent declares. A missing required field, the wrong type, or a value outside the options are refused with no run created.

Idempotency​

Send an idempotency key to make it safe to retry the request after a network timeout:

  • same key, same body → returns the original run;
  • same key, different body → refused.

The key does not get around rate limits.

Possible responses​

SituationWhat it means
AcceptedThe run was created
Key repeatedThe original run is returned
Input refusedThe data does not match what the agent declares
UnauthorizedA wrong credential or a nonexistent address — the same response for both
No longer existsThe address expired or was revoked
Too largeThe body exceeded the limit
Limit reachedThe address's rate or concurrency

The identical response for a wrong credential and a nonexistent address is deliberate: there is no way to discover valid identifiers by trial and error.

Following a run​

With the run's identifier you can:

ActionUse
Query the stateFind out whether it completed, failed, or is waiting
Read the timelineThe events, in order, with cursor-based resumption
CancelCooperative cancellation, checked between steps
Re-runCreates a new run from the same version

The timeline records semantic state. It exposes neither the model's internal reasoning nor token counts.

Triggering as a person​

With an Imaginne session, a script can trigger an agent manually, giving the environment and the input. The same rate limit as a manual run from Studio applies.

Response format​

Success and error have distinct, stable envelopes. Errors carry a stable code — the text may evolve, the code does not — and, where applicable, the list of fields with problems.

Isolation​

Every resource belongs to an organization, derived from the credential. A resource belonging to another organization answers as nonexistent, not as "no permission".

Getting the contract​

The full contract, for your installation's version, is provided by the team that administers the platform.

Next steps​