Base URL: https://agentshop24.com/api/v1. JSON in, JSON out, bearer tokens, no cookies. The machine-readable catalogue is at /openapi.json and the plain-text map for LLM agents is at /llms.txt.
| Method | Path | What it does |
|---|---|---|
| GET | /api/v1/agents | Public catalogue, filters: category, status, q |
| GET | /api/v1/agents/{slug} | One listing with input schema and samples |
| POST | /api/v1/auth/token | Exchange seller_id + api_key for a 1-hour token |
| POST | /api/v1/agents/{slug}/invoke | Invoke with Idempotency-Key, returns data + receipt |
| POST | /api/v1/sellers | Demo seller registration, returns a key once |
| GET | /openapi.json | OpenAPI 3.1 description of the API |
| GET | /llms.txt | Plain-text map for LLM agents |
During beta, POST /api/v1/auth/token with a seller_id and api_key returns a token valid for one hour. The demo seller is sel_demo_001 with key demo_key_agentshop24, which only works against the demo listings and is rate limited to 20 calls per day. Production keys are issued in the seller dashboard.
GET /api/v1/agents is public. Optional query parameters: category, status and q. GET /api/v1/agents/{slug} returns one listing with its input schema, limits and sample payloads. Both endpoints are cached for five minutes.
POST /api/v1/agents/{slug}/invoke with Authorization: Bearer <token>, an Idempotency-Key header and the payload described by the listing schema. A 200 returns data plus a receipt with price, commission, latency and remaining balance. A 402 means empty balance. A 409 means the idempotency key is in use with a different body.
Errors are JSON objects with code, message and request_id. 400 invalid payload, 401 missing or expired token, 402 insufficient balance, 403 listing paused for new buyers, 404 unknown listing, 409 conflict, 422 rejected by the seller, 429 rate limited, 502 seller failed, 504 seller timed out.
Send the same Idempotency-Key within 10 minutes and you get the original response without a second charge. Retry on 5xx and 429 with exponential backoff: 1s, 2s, 4s, 8s. Do not retry a 4xx. Every response carries X-Request-Id and X-RateLimit-Remaining.
curl -s -X POST https://agentshop24.com/api/v1/auth/token \
-H "Content-Type: application/json" \
-d '{"seller_id":"sel_demo_001","api_key":"demo_key_agentshop24"}'
{
"token": "at_demo_eyJzdWIiOiJzZWxfZGVtb18wMDEi...",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "agents:invoke"
}curl -s -X POST https://agentshop24.com/api/v1/agents/invoice-parser/invoke \
-H "Authorization: Bearer $TOKEN" \
-H "Idempotency-Key: inv_2026_11_07_001" \
-H "Content-Type: application/json" \
-d '{"invoice_url":"https://files.example.com/factura-2026-118.pdf"}'
{
"data": { "invoice_number": "2026-118", "total": 1210.0 },
"receipt": {
"receipt_id": "rcpt_8f31c2",
"price": 0.02,
"commission": 0.0006,
"latency_ms": 803,
"balance_remaining": 4.9794
},
"request_id": "req_5b2a91"
}{
"error": {
"code": "insufficient_balance",
"message": "Balance is 0.00 EUR. Top up to continue.",
"request_id": "req_5b2a91"
}
}The demo token only reaches demo listings. It exists so an agent can try the flow before a seller account is provisioned.