For AI agents: this page is also available as Markdown at https://docs.refabric.com/task-apis/calling-tasks/client-setup.md, and the index of every page is https://docs.refabric.com/llms.txt.
Task APIs › Calling tasks
Client setup
Set up the HTTP client that calls Refabric: where it runs, where the key comes from, and what it must do itself.
You call the API with a plain HTTP client. This page sets one up once, so every later example is a single call.
Server, not browser
Your client runs on your server. A key is a secret that spends your credits, and the API refuses a
key sent from a browser — any request with an Origin header — with 403 api_key_not_allowed_here,
on every operation. To call Refabric from a web or mobile app, send the app's requests to your own
server and call Refabric from there (Proxy setup).
Install
Nothing beyond your language's HTTP client: pip install requests for Python; fetch is built into
Node.js 18 or later.
Set the key
Read the key from the environment, never from source code:
export REFABRIC_API_KEY="<key>"Use one variable name everywhere — REFABRIC_API_KEY — so examples and scripts find it the same
way (Get your API key).
First call
A read that needs a key and spends no credits. A 200 with your balance means the setup works.
import os, requests
API = "https://api.refabric.com/v1"
s = requests.Session()
s.headers["Authorization"] = f"Key {os.environ['REFABRIC_API_KEY']}"
r = s.get(f"{API}/account/balance", timeout=30)
r.raise_for_status()
print(r.json())What your client must do
Build these once in your client:
| Concern | What to do | Where it is explained |
|---|---|---|
| Retries | retry when the error's retryable is true, with backoff; resend a submit with the same Idempotency-Key | Task errors |
| Rate limits | on 429, wait Retry-After seconds | Limits |
| Polling | read the job every few seconds at most; prefer a webhook for long jobs | Asynchronous jobs |
| Waiting | with Prefer: wait=N, set the HTTP timeout longer than N (at most 60 seconds of waiting) | Synchronous |
| Pagination | follow next_cursor while has_more is true | Conventions |
| Errors | branch on error.code, never on message | Task errors |