Listaro Docs

REST authentication and errors

Scoped keys, canonical operation inputs, safe retries, and result completeness.

Endpoint and authentication

Your application origin hosts POST /api/v1/operations/{tool}. The JSON body is the canonical tool input object, without a surrounding tool or payload envelope.

Send Authorization: Bearer YOUR_LISTARO_API_KEY and Content-Type: application/json. Each key belongs to one workspace and explicitly selected tool scopes. Rotation reveals a replacement secret once; revocation blocks the old key.

Find the origin in Integrations. Download OpenAPI 3.1 or the Postman collection. Keep keys in private environment variables and redact them from logs.

Example

curl "$LISTARO_BASE_URL/api/v1/operations/scrape_page" \
  -H "Authorization: Bearer $LISTARO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: scrape-example-unique-request" \
  -d '{"url":"https://example.org","formats":["markdown","metadata"],"renderMode":"never"}'

Use a fresh request key for new work. Reuse the same key only with exactly the same original arguments after an uncertain response. A conflicting reuse returns an explicit error.

Jobs and pagination

Asynchronous operations return a job reference. Call get_job to inspect progress and terminal status. Use returned cursors unchanged when reading get_crawl, get_change_report, or list_watches. Cursor pagination is bounded; keep any reported partial-result warnings.

Cancellation preserves completed evidence. Browser sessions expire; explicitly close them when finished.

Artifacts

Use get_artifact with an authorized artifact ID. Reads are bounded ranges with an offset, requested byte limit, and UTF-8 or base64 encoding. A single range is not a complete download. The console assembles bounded downloads and verifies their integrity.

Hosted document parsing accepts a public URL or an authorized artifact. Local filesystem paths are unavailable.

Errors and retries

Errors include a stable error.code and readable error.message. Where supplied, retain the request ID for support.

  • 400: invalid JSON, parameters, or request key.
  • 401: missing, expired, or revoked authentication.
  • 403: missing workspace access, scope, or operation permission.
  • 404: unavailable resource in the selected workspace.
  • 409: conflicting request or resource state.
  • 413 or 415: body size or media-type restriction.
  • 429: request or concurrency limit.
  • 502, 503, or 504: unavailable engine/provider, invalid upstream response, or uncertain outcome.

For an uncertain outcome, inspect history before retrying with the original key. Avoid automatic loops. An HTTP success may still contain partial data, warnings, or unavailable fields.

MCP is a separate transport

The remote MCP endpoint is /mcp. It supports scoped API keys and OAuth connections. See MCP setup. Account cookies do not authenticate external MCP requests.

On this page