Authentication

Every request that reads or spends your credits needs an API key. Send it in the x-api-key header:

curl "https://pullwire.dev/api/v1/me" -H "x-api-key: $PULLWIRE_API_KEY"

Authorization: Bearer works too, so clients that only know Bearer tokens need no extra setup:

curl "https://pullwire.dev/api/v1/me" -H "Authorization: Bearer $PULLWIRE_API_KEY"

If a request sends both headers, x-api-key is used.

Two endpoints are public and need no key: the tool catalog (GET /api/v1/tools) and the OpenAPI description (GET /api/v1/openapi.json).

API keysCopy Anchor Link

• Keys look like af_live_ followed by 56 hex characters. The first 8 characters after af_live_ are the visible prefix, so you can tell your keys apart without seeing the secret.
• The full key is shown once, when you create it. We store only a SHA-256 hash of the key, never the key itself, so nobody can read it back from our database.
• A revoked key stops working immediately and answers with 401 UNAUTHORIZED.
• Each key belongs to one organization. Runs started with the key spend that organization's credits, and the key can only see that organization's runs.

Keep your key safeCopy Anchor Link

• Store it in an environment variable or a secret manager, not in your code or repository.
• Call the API from your server or your agent's backend, never from a browser or a mobile app, where anyone can read the key.
• Use one key per app or agent, so you can revoke one without breaking the others.

Rate limitCopy Anchor Link

Each key can send a burst of 120 requests, then 60 per minute. A new or rested key can fire 120 calls at once, for example a batch of short runs. After that it gets one more request every second, so steady use of 60 per minute never hits the limit. When the key is out of requests you get 429 RATE_LIMITED with a Retry-After header that says how many seconds to wait. The limit counts requests, not results: one run that returns 200 results is one request.

A 429 also carries X-RateLimit-Limit (the burst size, 120), X-RateLimit-Remaining (requests left, 0 on a 429) and X-RateLimit-Reset (seconds until the next request is allowed, same as Retry-After). The same values are sent as RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset.

For bigger jobs, put more items into one run instead of sending many small runs, and add ?async=1 so a long run is not cut off after 25 seconds. See Runs.

ErrorsCopy Anchor Link

All error codes are listed on the Errors page.