Quickstart

This walks the golden path with nothing but curl: point an agent at a workspace, give it a task, watch the run, and collect the files it produced.

create a workspace → upload input files → start an agent run
→ poll until done → collect the output artifacts

Everything below runs against production with a fresh key. Prefer code? The same flow in TypeScript is a few lines with @arg-ai/sdk.

Use a user-owned API key for this quickstart. Creating a workspace with POST /api/workspaces requires a user principal and returns 403 for service-account keys — see Step 2 for the unattended alternative.

Prerequisites

Create a user-owned key at arg.ai/platform/api-keys, then export it. The plaintext key (arg_live_…) is shown only once.

export ARG_API_KEY="arg_live_your_key_here"
export ARG_API="https://api.arg.ai"

Create a workspace

A workspace is the container an agent does work inside — its files persist across runs.

curl -sS -X POST "$ARG_API/api/workspaces" \
  -H "X-API-Key: $ARG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "quickstart"}'

{
  "id": "8f3c…",
  "name": "quickstart",
  "icon_emoji": null,
  "versioning_enabled": true,
  "visibility": "org",
  "member_default_access": "full",
  "storage_region": "oc",
  "created_at": "2026-06-11T00:00:00.000Z",
  "sort_order": 0
}

Save the id:

export WS="8f3c…"

Service-account keys get 403 here (POST /api/workspaces requires a user principal). For unattended automation, create the workspace under an organization instead:

curl -sS -X POST "$ARG_API/api/organizations/$ORG_ID/workspaces" \
  -H "X-API-Key: $ARG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "quickstart"}'

Upload an input file

Upload a file the agent can work on. The upload is multipart/form-data; the optional path query sets the destination folder.

printf 'region,revenue\nAPAC,120\nEMEA,90\nAMER,150\n' > data.csv

curl -sS -X POST "$ARG_API/api/workspaces/$WS/files/upload?path=/" \
  -H "X-API-Key: $ARG_API_KEY" \
  -F "[email protected]"

{ "name": "data.csv", "path": "/data.csv", "type": "file", "size": 34, "revision": "…" }

Start an agent run

A run is a chat plus a turn. First create the chat, then send the task. Pass workspace_id so the agent can see your files.

CHAT=$(curl -sS -X POST "$ARG_API/api/agent" \
  -H "X-API-Key: $ARG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "quickstart run"}' | jq -r .id)

curl -sS -X POST "$ARG_API/api/agent/message" \
  -H "X-API-Key: $ARG_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"chat_id\": \"$CHAT\",
    \"workspace_id\": \"$WS\",
    \"model\": \"anthropic/claude-haiku-4.5\",
    \"message\": \"Read data.csv and write a summary.txt with total revenue by region.\"
  }"

A 200 means the turn started executing — keep call_id and job_id:

{ "job_id": "job_…", "call_id": "call_…", "chat_id": "…" }

If a turn is already running on this chat, you get a 202 instead — the new turn was queued behind it:

{ "status": "queued", "queue_id": "q_…", "position": 1, "chat_id": "…" }

export CHAT CALL="call_…" JOB="job_…"

Poll until the run finishes

Poll the status endpoint until status is completed or error. It reports pending while the run is in flight (it does not stream intermediate events).

curl -sS "$ARG_API/api/agent/status/$CALL?chat_id=$CHAT" \
  -H "X-API-Key: $ARG_API_KEY"

{
  "status": "completed",
  "result": {
    "status": "completed",
    "chatId": "…",
    "response": "I wrote summary.txt with revenue totals by region.",
    "toolOutputs": [
      { "tool": "write_file", "args": { "path": "/summary.txt" }, "result": "ok" }
    ]
  }
}

The toolOutputs array names every file the agent wrote — a quick way to find your artifacts.

Collect the output artifacts

List the workspace tree, then download what the agent produced.

curl -sS "$ARG_API/api/workspaces/$WS/files/tree" \
  -H "X-API-Key: $ARG_API_KEY"

curl -sS "$ARG_API/api/workspaces/$WS/files/download?path=/summary.txt" \
  -H "X-API-Key: $ARG_API_KEY" -o summary.txt

cat summary.txt

For text files you can read the content inline instead of downloading bytes:

curl -sS "$ARG_API/api/workspaces/$WS/files/content?path=/summary.txt" \
  -H "X-API-Key: $ARG_API_KEY"

{ "path": "/summary.txt", "name": "summary.txt", "content": "APAC 120\nEMEA 90\nAMER 150\n", "encoding": "utf-8", "size": 27, "mime_type": "text/plain" }

(Optional) iterate, then clean up

Send another turn to the same chat to build on the work:

curl -sS -X POST "$ARG_API/api/agent/message" \
  -H "X-API-Key: $ARG_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"chat_id\": \"$CHAT\", \"workspace_id\": \"$WS\", \"message\": \"Now format summary.txt as a markdown table.\"}"

Release the finished job, and delete the chat when you’re done:

curl -sS -X POST "$ARG_API/api/agent/cleanup/$JOB?chat_id=$CHAT" \
  -H "X-API-Key: $ARG_API_KEY"

curl -sS -X DELETE "$ARG_API/api/chats/$CHAT" \
  -H "X-API-Key: $ARG_API_KEY"

Error format

Every error is a JSON object with a detail string and the matching HTTP status:

{ "detail": "Not authorized" }

Common statuses: 401 (bad/missing key), 403 (authenticated but not permitted — e.g. a service-account key creating a workspace), 404 (not found), 429 (rate limited).

Next steps

Skip the plumbing. @arg-ai/sdk wraps this exact flow (auth, retries, typed errors, the Run lifecycle, and resilient file uploads), so the golden path is a handful of typed calls instead of raw curl.
Go deeper on runs. Agent runs covers queueing a follow-up, steering a turn already in flight, and stopping one that has gone wrong.
Run code yourself. Execute shell commands and edit files directly with the tools API, no model in the loop.
Make it recurring. Unattended runs covers service accounts, schedules, and being told when something breaks.
Browse the full surface in the API Reference.

Getting started

Building with agents

Core concepts

Apps

Arg SDK

Integrations

Command line

Recipes & patterns

Changelog

Prerequisites

Error format

Next steps

​Prerequisites

​Error format

​Next steps

Prerequisites

Error format

Next steps