Authentication

The API uses direct-client public API keys generated in Sillage workspace settings. These keys authorize access to the workspace linked to the key.

Include the API key in the Authorization header:

Authorization: Bearer <YOUR_API_KEY>

Example request

curl -X POST "https://api.getsillage.com/api/v2/contents/query" \
  -H "Authorization: Bearer $SILLAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page_size": 5}'

Status codes

Status	Meaning
200	The request succeeded.
400	The request parameters are invalid.
401	The API key is missing, invalid, or revoked.
402	Insufficient credits to complete the request.
403	The key does not have access to the requested workspace resource.
404	The requested resource does not exist or is not visible to the key.
409	Conflict with current state of the resource.
422	Unprocessable entity. The request body is structurally valid but semantically invalid.
429	Too many requests. The `Retry-After` header indicates when to retry.
500	An unexpected server error occurred.

Error model

v2 endpoints (/api/v2/...) return errors as RFC 9457 problem documents. The response Content-Type is application/problem+json.

Each problem document contains six fields. The type URI is a stable slug registered at https://docs.getsillage.com/errors/<slug>. When no specific type applies, type is about:blank. The errors extension field is present only on validation errors (400, 422) and maps each invalid field to a list of messages.

{
  "type": "https://docs.getsillage.com/errors/invalid-query",
  "title": "Invalid query parameters",
  "status": 400,
  "detail": "page_size must be a positive integer",
  "instance": "/api/v2/contents",
  "errors": { "page_size": ["must be a positive integer"] }
}

The v1 endpoints (/v1/workspace/signals, /v1/workspace/leads) keep the legacy { "error": { status, name, message } } envelope. All v2 endpoints use the problem+json shape above.

Common response headers

Every response includes:

Header	Description
X-Request-Id	Request UUID for debugging and support.
X-Response-Time	Server response time.

Rate-limited responses (429) include:

Header	Description
X-RateLimit-Limit	Maximum number of requests allowed in the time window.
X-RateLimit-Remaining	Remaining requests in the current window.

When you receive a 429, read X-RateLimit-Remaining and back off before retrying.

Security

Treat API keys like passwords

Store them server-side, avoid exposing them in browsers, and rotate keys when a user leaves your organization or a key may have been copied.