> ## Documentation Index
> Fetch the complete documentation index at: https://hs-df36fa00.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Invoke Agent Async — POST /v1/agents/:agent_id/invoke-async

> Submit an agent invocation without blocking. Returns a receipt_id with status 'running'. Poll the receipt endpoint to check when the call completes.

Submits an agent invocation and returns immediately without waiting for the agent to complete. The gateway accepts the invocation, issues a `receipt_id`, and executes the call in the background. Use the returned `receipt_id` with the [receipts API](/api/receipts/get) to poll for completion.

This endpoint accepts exactly the same request body as [POST /v1/agents/:agent\_id/invoke](/api/agents/invoke).

## Request

```bash theme={null}
curl -X POST http://your-node:8042/v1/agents/stripe-agent/invoke-async \
  -H 'content-type: application/json' \
  -d '{
    "message": "Create a payment link for 15 AUD",
    "auth_token": "secret-token",
    "region": "AU"
  }'
```

### Path parameters

<ParamField path="agent_id" type="string" required>
  The unique identifier of the published agent to invoke.
</ParamField>

### Body parameters

All body parameters are identical to [POST /v1/agents/:agent\_id/invoke](/api/agents/invoke).

<ParamField body="input" type="object">
  Structured input payload forwarded to the agent.
</ParamField>

<ParamField body="message" type="string">
  Natural language instruction for the agent.
</ParamField>

<ParamField body="task_id" type="string">
  Optional A2A task identifier.
</ParamField>

<ParamField body="context_id" type="string">
  Optional A2A context identifier for multi-turn conversation state.
</ParamField>

<ParamField body="skill_id" type="string">
  Identifier of the specific agent skill to invoke.
</ParamField>

<ParamField body="auth_token" type="string">
  Bearer token or API key passed directly to the agent.
</ParamField>

<ParamField body="auth_context_id" type="string (UUID)">
  Reference to a stored auth context.
</ParamField>

<ParamField body="region" type="string">
  ISO country code of the calling region.
</ParamField>

<ParamField body="confirm_risky" type="boolean">
  Set to `true` to proceed with agents that require human approval. Defaults to `false`.
</ParamField>

<ParamField body="max_cost_units" type="integer">
  Maximum cost units you are willing to spend on this call.
</ParamField>

<ParamField body="settlement" type="object">
  Optional payment settlement request.

  <Expandable title="settlement fields">
    <ParamField body="layer" type="string">
      Either `"web2"` or `"web3"`. Defaults to `"web3"`.
    </ParamField>

    <ParamField body="rail" type="string">
      Payment rail identifier (e.g. `"x402"`).
    </ParamField>

    <ParamField body="request" type="object">
      Rail-specific payment request payload.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="agent_envelope" type="object">
  Raw A2A envelope to forward verbatim to the agent.
</ParamField>

## Response

Returns an `InvokeAgentResponse` immediately with `status` set to `"running"`.

<ResponseField name="agent_id" type="string">
  The agent that was invoked.
</ResponseField>

<ResponseField name="status" type="string">
  Always `"running"` for an async invocation. The call is still in progress.
</ResponseField>

<ResponseField name="receipt_id" type="string (UUID)">
  Unique identifier for the in-progress execution receipt. Poll `GET /v1/receipts/:receipt_id` to check when the status transitions to `"succeeded"` or `"failed"`.
</ResponseField>

<ResponseField name="message" type="string">
  Always `"ServiceNet invocation accepted"` for a successful async submission.
</ResponseField>

<ResponseField name="raw" type="object">
  Empty object at submission time. Populated on the receipt record once execution completes.
</ResponseField>

## Status codes

| Code              | Meaning                                                                                  |
| ----------------- | ---------------------------------------------------------------------------------------- |
| `200 OK`          | Invocation accepted. Returns the initial `InvokeAgentResponse` with `status: "running"`. |
| `403 Forbidden`   | Policy check failed before the invocation could be queued.                               |
| `404 Not Found`   | No published agent with the given `agent_id` exists.                                     |
| `502 Bad Gateway` | The gateway could not dispatch the invocation to the downstream agent endpoint.          |

## Example response

```json theme={null}
{
  "agent_id": "stripe-agent",
  "status": "running",
  "receipt_id": "f1e2d3c4-0000-0000-0000-000000000002",
  "message": "ServiceNet invocation accepted",
  "raw": {}
}
```

<Note>
  After receiving this response, poll `GET /v1/receipts/f1e2d3c4-0000-0000-0000-000000000002` to retrieve the execution outcome once `status` changes from `"running"` to `"succeeded"` or `"failed"`.
</Note>