> ## Documentation Index
> Fetch the complete documentation index at: https://docs.askactual.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Treat availability labels as authoritative. Do not present planned surfaces as live.
> The product MCP can act on Actual Jobs; the documentation MCP cannot.

# Quickstart

> Preview the intended Actual API integration flow.

<Warning>
  **Planned surface.** The Job API and SDKs are not currently published. This quickstart is a
  contract preview; it cannot yet be run against production.
</Warning>

## 1. Model a User request

Send the User's words and any values your application knows structurally. Actual preserves the request as provenance and interprets an Objective and Constraints. Ambiguity pauses for input instead of guessing.

```json theme={null}
{
  "request": "Get my air conditioner cooling again this week.",
  "constraints": []
}
```

## 2. Create a Job

The planned canonical operation is `POST /v1/jobs`. Mutations require authentication and an idempotency key.

```bash theme={null}
curl --request POST "https://api.askactual.com/v1/jobs" \
  --header "Authorization: Bearer $ACTUAL_API_KEY" \
  --header "Idempotency-Key: $REQUEST_ID" \
  --header "Content-Type: application/json" \
  --data '{"request":"Get my air conditioner cooling again this week.","constraints":[]}'
```

Use a unique stable value from your own operation as `REQUEST_ID`; do not reuse it for a different intent. Never put an API key in client-side code or source control.

## 3. Follow and revise the Job

The planned API will expose a point-in-time Job view and a resumable event stream. A changed Constraint creates a durable revision. Work derived from an older revision is invalidated rather than silently continuing.

## 4. Present Approval exactly

When Actual requests authority, show the complete immutable proposal. An Approval decision binds to its `proposalHash` and `jobRevision`. Authentication alone does not approve spending.

## 5. Wait for Verification

Do not treat a booking or payment response as completion. A Job has an Outcome only after successful Verification. If execution or Verification fails, the Job may enter Recovery.

<CardGroup cols={2}>
  <Card title="Authentication and idempotency" href="/guides/authentication-idempotency" />

  <Card title="Job lifecycle" href="/concepts/job-lifecycle" />
</CardGroup>