CodeLibra API

This section provides guidance for using CodeLibra public REST API endpoints.

For endpoint lists, parameters, and schemas use the OpenAPI reference: https://api.codelibra.io/docs.

You can explore how to use the API by using browser developer tools to observe the web app, which interfaces the CodeLibra servers through the API. Note: Do not use the internal (undocumented) API endpoints as they may change without notice.

URLs

• Base URL for v1 endpoints: https://api.codelibra.io/v1
• OpenAPI docs: https://api.codelibra.io/docs
• Machine-readable OpenAPI spec (JSON): https://api.codelibra.io/v1/openapi.json
• Health check: https://api.codelibra.io/healthz

Versioning

The API uses namespaced versions (for example, /v1). Backwards-compatible additions may appear within a version; breaking changes come with a new version.

Authentication

All public API endpoints require authentication via an API key.

• API keys can be created in the API Keys tab of the user area or by clicking here
• Header: X-API-Key: <your_key>
• Usage: Suitable for server-to-server automations where you can securely store the key.
• Treat API keys like passwords. Do not embed them in client-side code or public apps.
• API Keys can be elevated or not elevated; only elevated keys can access elevated security operations (the ones that require reauthentication or passkey access).

Testing

The API provides dedicated test endpoints to help you verify connectivity and authentication setup:

• GET /v1/test/hello — Public test endpoint that requires no authentication. Use this to verify basic API connectivity and that the service is responding correctly.

  curl https://api.codelibra.io/v1/test/hello
  

  Returns: "Hello world!" with 200 OK status.

• GET /v1/test/auth-hello — Authenticated test endpoint that requires a valid API key. Use this to verify that your authentication credentials are working correctly.

  curl -H "X-API-Key: <your_key>" https://api.codelibra.io/v1/test/auth-hello
  

  Returns: "Hello {User}!" with 200 OK status if authenticated, or 401 Unauthorized if the API key is missing or invalid.

• GET /v1/test/elevated-auth-hello — Elevated authentication test endpoint that requires a valid elevated API key. Use this endpoint to verify that elevated security is properly configured and your elevated credentials are valid.

  curl -H "X-API-Key: <your_elevated_key>" https://api.codelibra.io/v1/test/elevated-auth-hello
  

  Returns: "Hello {User} (elevated)!" with 200 OK status if authenticated with an elevated key, 401 Unauthorized if the API key is missing or invalid, or 403 Forbidden if the API key is not elevated.

These endpoints are useful for integration testing, health monitoring, and debugging authentication issues.

Data formats

• Request/response bodies are JSON.
• Field names are case-sensitive in lowerCamelCase as specified in the OpenAPI schemas.
• Timestamps are returned in ISO-8601 UTC unless stated otherwise.

Pagination and filtering

Some endpoints use offset/limit pagination and return the total count in a response header.

• Pagination parameters:
  • from (int, default 0): zero-based offset of the first item to return
  • limit (int): maximum number of items to return; a per-endpoint maximum (usually 100 items) applies
  • Some endpoints also accept ordering parameters:
    • order (string): a sortable field name supported by that endpoint
    • ascending (bool): sort direction; true for ascending, false for descending
• Response headers:
  • X-Total-Count: total number of items matching the request (before pagination)
• Filtering/search parameters used by some endpoints:
  • query (string): space-separated search terms; items match when all tokens are found in searchable fields (depending on endpoint)
  • exclude (string): space-separated tokens to exclude from results (only identifying fields are used like id, slug, etc.)

Notes:

• Not all endpoints support all parameters above. Refer to the OpenAPI reference for each route’s supported parameters.
• When limit is 0, endpoints return an empty list, but still include X-Total-Count.

Rate limiting

To maintain reliability and fairness, requests are rate-limited.

• Authenticated users receive a higher allowance per sliding window.
• Anonymous requests have a lower allowance.
• On limit exceed: the API returns 429 Too Many Requests and includes an X-RateLimit-Reset response header with a UNIX timestamp indicating when the window resets.
• Implement exponential backoff and respect X-RateLimit-Reset before retrying.

Errors

• The API uses standard HTTP status codes (2xx success, 4xx client errors, 5xx server errors).
• Error bodies follow RFC 7807 (Problem Details). Fields present in responses generated by our helper include:
  • title (string): short summary derived from the HTTP status, e.g., "BadRequest"
  • status (number): HTTP status code, e.g., 400
  • detail (string): human-readable explanation
  • code (number): stable machine-readable error code; see the complete list here
  • instance is omitted when not set, and type is typically omitted (defaults to about:blank).
• Concrete example (from accepting an organization invitation with the wrong user):

  {
    "title": "BadRequest",
    "status": 400,
    "detail": "Only the invited user can accept this invitation.",
    "code": 400010
  }
  

• Handle 401/403 by refreshing credentials or correcting permissions, and handle 409/422 by adjusting your request data.

Getting help

• Explore and try requests in the OpenAPI UI: https://api.codelibra.io/docs
• If you need to raise an issue, e-mail support@codelibra.com.