# Convert files with Converter API

Converter API converts documents, spreadsheets, images, ebooks, and
archives over plain HTTP. Agents can register themselves and start
converting immediately: no human, no pre-shared key, no signup form.

- Base URL: https://api-staging.converting.app
- Auth spec: https://api-staging.converting.app/auth.md (WorkOS agent auth)
- Authorization server metadata: https://api-staging.converting.app/.well-known/oauth-authorization-server
- Errors are RFC 7807 problem+json with a stable `code` field.

## 1. Register yourself (anonymous identity)

    curl -s -X POST https://api-staging.converting.app/agent/identity \
      -H "Content-Type: application/json" \
      -d '{"type":"anonymous"}'

The response contains:

- `identity_assertion`: short-lived JWT proving this identity (10 min).
- `claim_token`: STORE THIS SECRET DURABLY. It is the only way to
  later link this identity to a human account and keep your history.
- `user_code` and `verification_uri`: for the optional claim ceremony.

## 2. Exchange the assertion for an access token

    curl -s -X POST https://api-staging.converting.app/oauth2/token \
      -d grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer \
      -d assertion=IDENTITY_ASSERTION

Returns `access_token` (Bearer, expires in 1 hour). When it expires,
repeat steps 1-2, or re-register with your stored claim_token context.
Send it as `Authorization: Bearer ...` on every /v1 request.

## 3. Convert a file

List supported formats and pairs (no auth required):

    curl -s https://api-staging.converting.app/v1/formats

Create a job (returns a presigned upload URL):

    curl -s -X POST https://api-staging.converting.app/v1/jobs \
      -H "Authorization: Bearer ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{"source_format":"csv","target_format":"json","filename":"data.csv"}'

Upload the input bytes directly to object storage:

    curl -s -X PUT "UPLOAD_URL" --data-binary @data.csv

Start the conversion:

    curl -s -X POST https://api-staging.converting.app/v1/jobs/JOB_ID/start \
      -H "Authorization: Bearer ACCESS_TOKEN"

Poll until `status` is `done` (or `failed`):

    curl -s https://api-staging.converting.app/v1/jobs/JOB_ID \
      -H "Authorization: Bearer ACCESS_TOKEN"

Download the results:

    curl -s https://api-staging.converting.app/v1/jobs/JOB_ID/artifacts \
      -H "Authorization: Bearer ACCESS_TOKEN"

## 4. Free trial and what happens when it ends

Anonymous agents get 5 free conversions. This allowance is lifetime per
identity, not per day, and is not reset by new tokens. Successful
`POST /v1/jobs` responses include `X-Conversions-Remaining` so you can
warn your user before hitting the wall.

When the trial is exhausted, job creation fails with HTTP 402:

    {
      "code": "agent_trial_exhausted",
      "detail": "Free agent trial of 5 conversions is used. ...",
      "claim_endpoint": "https://api-staging.converting.app/agent/identity/claim",
      "pricing_url": "https://staging.converting.app/pricing",
      "docs_url": "https://api-staging.converting.app/convert.md"
    }

To continue, your human user must claim this agent onto their account:

1. Start a claim with your stored claim_token:

       curl -s -X POST https://api-staging.converting.app/agent/identity/claim \
         -H "Content-Type: application/json" \
         -d '{"claim_token":"CLAIM_TOKEN"}'

2. Show the returned `verification_uri` and `user_code` to your user
   and ask them to open it in a browser and approve the claim.

3. Poll the token endpoint until the claim completes
   (poll no faster than the returned `interval`; `authorization_pending`
   means keep waiting, `slow_down` means back off):

       curl -s -X POST https://api-staging.converting.app/oauth2/token \
         -d grant_type=urn:workos:agent-auth:grant-type:claim \
         -d claim_attempt_token=CLAIM_ATTEMPT_TOKEN

4. The returned access token is bound to the user's account and plan
   (Free: 10 conversions/day; paid plans have monthly quotas). Your
   pre-claim job history moves with you. If the user needs more
   volume, send them to https://staging.converting.app/pricing.

## Limits and etiquette

- Trial: 5 lifetime conversions, 25 MB max upload, 1 job at a time.
- Rate limit: 60 requests/min per token on job creation; on 429 or 503
  honor the Retry-After header.
- Files are deleted when the conversion completes; download artifacts
  promptly.

## Links

- Pricing: https://staging.converting.app/pricing
- Terms: https://staging.converting.app/terms
- Privacy: https://staging.converting.app/privacy
- Contact: support@converting.app