Docs / Curl recipes

Curl recipes

Task-oriented companion to the API reference. Every recipe is a complete pipeline you can paste into a terminal after substituting your token. Most pipe through jq for clarity — drop the pipe if you just want the raw response.

Mint a token at /me/api-tokens. Tokens look like arti_… and are shown once on creation.

• Smoke-test your token

  First call after minting a token. Confirms it's valid + which user it belongs to. Useful in CI as the very first step.

  curl -fsS \
    -H "Authorization: Bearer arti_<your-token>" \
    https://artinstring.com/api/v1/me

• Find a prompt by name

  Substring search across title + slug + description. Returns the matching catalog rows plus a total so you know how many more are out there beyond the current page.

  curl -fsS \
    -H "Authorization: Bearer arti_<your-token>" \
    "https://artinstring.com/api/v1/prompts?q=portrait&limit=5" \
    | jq '{ count, total, first: .prompts[0].slug }'

  The `total` field reflects the same `?q` + `?modality` + `?tier` + `?provider` filters as the rows query — useful for `Showing X of Y` UIs without a follow-up call.

• List your last 5 completed runs

  Quickest way to verify your last few runs landed. Status filter + small limit keeps the response tiny.

  curl -fsS \
    -H "Authorization: Bearer arti_<your-token>" \
    "https://artinstring.com/api/v1/runs?status=completed" \
    | jq '.runs[:5] | map({ id, completedAt, promptSlug })'

• Paginate through every run you've ever made

  Cursor-based pagination. Each page is up to 50 rows; pass the previous response's nextCursor as `?cursor=` to continue. The `total` field stays stable across pages so you can render "page X of N" honestly.

  # Page 1
  curl -fsS \
    -H "Authorization: Bearer arti_<your-token>" \
    https://artinstring.com/api/v1/runs
  
  # Page 2 — replace <cursor> with the previous response's nextCursor
  curl -fsS \
    -H "Authorization: Bearer arti_<your-token>" \
    "https://artinstring.com/api/v1/runs?cursor=<cursor>"

• Fire and poll a run

  Dispatch a run, capture the runId, then poll /runs/<id> until status is no longer `queued` or `running`. The simplest non-streaming integration pattern.

  # 1. Dispatch
  RUN_ID=$(curl -fsS -X POST https://artinstring.com/api/v1/runs \
    -H "Authorization: Bearer arti_<your-token>" \
    -H "Content-Type: application/json" \
    -d '{"promptId":"<prompt-uuid>","vars":{"subject":"a stoic owl"}}' \
    | jq -r '.runId')
  
  # 2. Poll every 2s until the run terminates
  while true; do
    RESP=$(curl -fsS \
      -H "Authorization: Bearer arti_<your-token>" \
      "https://artinstring.com/api/v1/runs/$RUN_ID")
    STATUS=$(echo "$RESP" | jq -r '.status')
    echo "$STATUS"
    case "$STATUS" in
      completed|failed|cancelled) echo "$RESP" | jq '.output'; break ;;
    esac
    sleep 2
  done

  If you'd rather receive a stream than poll, use `GET /api/runs/<id>/stream` (Server-Sent Events).

• Discover catalog totals at a glance

  Every list endpoint returns `count` (rows in the response), `total` (rows matching the filters), and an `X-Total-Count` response header for tooling that can't introspect JSON.

  # Header-only — no body, just the totals
  curl -sI \
    -H "Authorization: Bearer arti_<your-token>" \
    "https://artinstring.com/api/v1/prompts?modality=image" \
    | grep -i x-total-count
  
  # Or pull the same number out of the body
  curl -fsS \
    -H "Authorization: Bearer arti_<your-token>" \
    "https://artinstring.com/api/v1/prompts?modality=image&limit=1" \
    | jq '.total'

• Watch your remaining quota

  Replicate-routed quota usage by modality. Useful as a pre-flight check before you POST a run, so the integration can fail loudly with a friendly message instead of swallowing a 429.

  curl -fsS \
    -H "Authorization: Bearer arti_<your-token>" \
    https://artinstring.com/api/v1/me/quotas \
    | jq '.quotas'

• Pick a random prompt and run it

  Two calls: random prompt → POST run. Good "hello world" for a fresh integration that just wants to prove the round-trip works without picking a specific prompt.

  PROMPT=$(curl -fsS \
    -H "Authorization: Bearer arti_<your-token>" \
    https://artinstring.com/api/v1/prompts/random)
  
  PROMPT_ID=$(echo "$PROMPT" | jq -r '.id')
  echo "Picked: $(echo "$PROMPT" | jq -r '.title')"
  
  curl -fsS -X POST https://artinstring.com/api/v1/runs \
    -H "Authorization: Bearer arti_<your-token>" \
    -H "Content-Type: application/json" \
    -d "{\"promptId\":\"$PROMPT_ID\",\"vars\":{}}"

  If the prompt declares required variables, the dispatch returns 400 `missing_variables` — wire those in based on the prompt's `variableSchema`.

Looking for the full reference instead? /docs/api lists every endpoint with response shape and error codes.