API Reference

Run your LLMWeave workflows programmatically — trigger a run, feed it data, and read the result over a small REST API. Everything is JSON over HTTPS. The base URL is https://llmweave.com/api/v1.

Quickstart

1. Create an API key in Settings → API keys (paid plans). Copy it — it’s shown only once.

2. (Optional) Upload a file to feed into the run. 3. Trigger the run. 4. Poll until it completes.

# 1. (optional) upload a CSV — returns an attachment id
curl -X POST https://llmweave.com/api/v1/attachments \
  -H "Authorization: Bearer $LLMWEAVE_API_KEY" \
  -F "file=@timesheets.csv"
# → { "data": { "id": "att_...", "kind": "csv", "extraction_status": "extracted" } }

# 2. trigger a workflow run (attachment_ids optional)
curl -X POST https://llmweave.com/api/v1/workflows/$WORKFLOW_ID/runs \
  -H "Authorization: Bearer $LLMWEAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "input_text": "Summarize hours by project", "attachment_ids": ["att_..."] }'
# → 201 { "data": { "id": "<run_id>", "status": "pending", "links": { ... } } }

# 3. poll until status is "completed" (or "failed" / "awaiting_input")
curl https://llmweave.com/api/v1/workflow-runs/<run_id> \
  -H "Authorization: Bearer $LLMWEAVE_API_KEY"

Authentication

Send your key as a bearer token on every request. Keys look like llmw_live_… and are issued in Settings → API keys. API access requires a paid plan; team members are covered by their team’s plan.

Authorization: Bearer llmw_live_xxxxxxxxxxxxxxxxxxxx

Each key carries scopes — workflows:read (list/read) and workflow_runs:create(create runs, upload files). A key may also be restricted to an allowlist of specific workflow ids; calls outside the allowlist return 404 (the workflow is treated as non-existent for that key). Keys are personal-scope in v1 — a run is billed to the key owner’s account. Store keys as secrets and revoke any that leak.

Conventions

Errors

Every error uses the same envelope, with a request_id you can quote in support:

{ "error": { "code": "INSUFFICIENT_CREDITS", "message": "Insufficient credits. Estimated cost: $0.12.", "request_id": "req_..." } }

Idempotency

For POST requests that create a run, send an Idempotency-Key header (any unique string ≤256 chars, e.g. a UUID). A retry with the same key returns the original response instead of starting a second run. Reusing a key with a different body — or while the first request is still in flight — returns 409. The key is bound to the exact method + path, so the same value can’t replay against a different endpoint.

Rate limits

Run creation is rate-limited per hour, scaled to your plan and shared with the web app. Over the limit returns 429with limit and remaining fields — back off and retry.

Endpoints

Who am I

Returns the account and key behind the token — handy for verifying a key works and which scopes it has.

{ "data": { "user_id": "...", "email": "you@example.com", "plan": "team",
           "key_id": "...", "key_name": "n8n integration",
           "key_scopes": ["workflows:read", "workflow_runs:create"] } }

List workflows

Lists workflows the key can run (its allowlist, if set). Requires workflows:read. Optional ?limit.

{ "data": [ { "id": "...", "name": "Timesheet Insights", "description": "...", "updated_at": "..." } ] }

Upload a file

Multipart upload of a single file field. Returns an attachment id to pass as attachment_ids on a run. Requires workflow_runs:create + a paid plan. Supported types include CSV, PDF, DOCX, JSON, and images (see the picker in-app for the full list and size cap). CSV/XLSX text extraction reads up to the first 5,000 rows (20MB max) and notes any truncation in the extracted text.

curl -X POST https://llmweave.com/api/v1/attachments \
  -H "Authorization: Bearer $LLMWEAVE_API_KEY" \
  -F "file=@data.csv"

→ 201 { "data": { "id": "att_...", "original_filename": "data.csv",
                  "kind": "csv", "byte_size": 20480, "extraction_status": "extracted", "row_count": 500 } }

Create a run

Starts a workflow run and returns immediately with a run id. Requires workflow_runs:create. Body fields:

→ 201 { "data": { "id": "<run_id>", "workflow_id": "<id>", "status": "pending",
                  "created_at": "...",
                  "links": { "self": "https://llmweave.com/api/v1/workflow-runs/<run_id>",
                             "app":  "https://llmweave.com/weave/workflows/<id>/runs/<run_id>" } } }

Common errors: 402 PAID_PLAN_REQUIRED / 402 INSUFFICIENT_CREDITS,403 NO_ALLOCATION (team member without a credit allocation), 404 (workflow not found / not allowed for this key),429 RATE_LIMITED.

Get a run

Poll this until status is terminal. Statuses: pending → running →completed | failed | awaiting_input (a human-review step is waiting). A poll every 2–5 seconds is plenty. Returns the result, final cost, and a per-stage cost breakdown.

{ "data": { "id": "...", "workflow_id": "...", "status": "completed",
            "result": { ... }, "cost_cents": 12, "cost_breakdown": [ ... ],
            "human_input_request": null, "started_at": "...", "completed_at": "..." } }

No-code & automation tools

Any tool that can make an authenticated HTTP request works — n8n (HTTP Request node), Zapier (Webhooks → Custom Request), and Make (HTTP module). Configure them the same way: method POST, URL https://llmweave.com/api/v1/workflows/<id>/runs, an Authorization: Bearer … header, JSON body. Then add a second step that pollshttps://llmweave.com/api/v1/workflow-runs/<id> until status is completed.

Status codes

Ready to start? Create an API key →