Skip to main content

REST / cURL reference

Base URL: https://api.asgrefinery.io (or http://localhost:8081).

Replace $API_KEY with your key. Authenticated requests use:

Authorization: Bearer <api_key>

Authentication​

Register — POST /v1/customers​

curl -sS -X POST https://api.asgrefinery.io/v1/customers \
  -H 'Content-Type: application/json' \
  -d '{"name":"Acme","email":"ops@acme.example"}'

201:

{
  "customer_id": "cust_...",
  "api_key": "sk_sandbox_...",
  "tier": "sandbox",
  "label_quota": 500,
  "message": "Store this API key securely — it cannot be retrieved again."
}

Profile — GET /v1/customers/me​

curl -sS -H "Authorization: Bearer $API_KEY" \
  https://api.asgrefinery.io/v1/customers/me

Tasks​

Submit — POST /v1/tasks​

curl -sS -X POST https://api.asgrefinery.io/v1/tasks \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"type":"image_classification","data_url":"https://example.com/i.jpg","label_spec":{"question":"Q?","options":["a","b"]}}'

202:

{
  "task_id": "tsk_...",
  "status": "pending",
  "created_at": "2026-04-09T12:00:00Z"
}

Batch — POST /v1/tasks/batch​

curl -sS -X POST https://api.asgrefinery.io/v1/tasks/batch \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"tasks":[{"type":"image_classification","data_url":"https://ex.com/a.jpg","label_spec":{"question":"Q?","options":["a","b"]}}]}'

202:

{
  "batch_id": "bat_...",
  "task_count": 1,
  "status": "accepted"
}

Status — GET /v1/tasks/{id}​

curl -sS -H "Authorization: Bearer $API_KEY" \
  https://api.asgrefinery.io/v1/tasks/tsk_xxx

200:

{
  "task_id": "tsk_xxx",
  "status": "pending",
  "task_type": "image_classification",
  "data_url": "https://example.com/i.jpg",
  "created_at": "2026-04-09T12:00:00Z"
}

Result — GET /v1/tasks/{id}/result​

curl -sS -H "Authorization: Bearer $API_KEY" \
  https://api.asgrefinery.io/v1/tasks/tsk_xxx/result

202 (in progress) / 200 (ready) — see Retrieving results.

Webhooks​

Register — POST /v1/webhooks​

curl -sS -X POST https://api.asgrefinery.io/v1/webhooks \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"callback_url":"https://example.com/hook","secret":"whsec_xxx"}'

List — GET /v1/webhooks​

curl -sS -H "Authorization: Bearer $API_KEY" \
  https://api.asgrefinery.io/v1/webhooks

Delete — DELETE /v1/webhooks/{id}​

curl -sS -X DELETE -H "Authorization: Bearer $API_KEY" \
  https://api.asgrefinery.io/v1/webhooks/whk_xxx

Batch jobs​

Create — POST /v1/jobs​

curl -sS -X POST https://api.asgrefinery.io/v1/jobs \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"manifest_url":"https://bucket/manifest.jsonl","label_spec":{"question":"Q","options":["a","b"]},"s3_credentials":{"access_key_id":"x","secret_access_key":"y","region":"us-east-1"}}'

Status — GET /v1/jobs/{id}​

curl -sS -H "Authorization: Bearer $API_KEY" \
  https://api.asgrefinery.io/v1/jobs/job_xxx

Export — GET /v1/jobs/{id}/export​

curl -sS -H "Authorization: Bearer $API_KEY" \
  https://api.asgrefinery.io/v1/jobs/job_xxx/export

Returns JSONL when job is completed.

Billing​

Usage — GET /v1/billing/usage​

curl -sS -H "Authorization: Bearer $API_KEY" \
  "https://api.asgrefinery.io/v1/billing/usage?month=2026-04"

Invoices — GET /v1/billing/invoices​

curl -sS -H "Authorization: Bearer $API_KEY" \
  https://api.asgrefinery.io/v1/billing/invoices

Dashboard​

Overview — GET /v1/dashboard/overview​

curl -sS -H "Authorization: Bearer $API_KEY" \
  https://api.asgrefinery.io/v1/dashboard/overview

Tasks — GET /v1/dashboard/tasks​

curl -sS -H "Authorization: Bearer $API_KEY" \
  "https://api.asgrefinery.io/v1/dashboard/tasks?page=1&per_page=25&status=&sort=created_at_desc"

Quality — GET /v1/dashboard/quality​

curl -sS -H "Authorization: Bearer $API_KEY" \
  https://api.asgrefinery.io/v1/dashboard/quality

Usage stats — GET /v1/dashboard/usage​

curl -sS -H "Authorization: Bearer $API_KEY" \
  https://api.asgrefinery.io/v1/dashboard/usage

System​

Health — GET /v1/health (no auth)​

curl -sS https://api.asgrefinery.io/v1/health

200:

{
  "ok": true,
  "service": "asg-gateway"
}