API Reference¶

Ospobox provides a REST API for programmatic access to all features.

Base URL¶

https://your-ospobox-instance.com/api

For local development:

http://localhost:8000/api

Authentication¶

Most API endpoints require authentication using JWT Bearer tokens.

curl -H "Authorization: Bearer <your-token>" \
     https://api.ospobox.io/api/organizations/

See Authentication for details on obtaining tokens.

Response Format¶

All responses are JSON. Successful responses return data directly:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "my-organization",
  "platform": "github"
}

Error responses include an error message:

{
  "detail": "Organization not found"
}

HTTP Status Codes¶

Rate Limiting¶

API requests are rate limited to prevent abuse:

Rate limit headers are included in responses:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1640000000

API Endpoints¶

Paths below are relative to the base URL, so /auth/login is /api/auth/login. The web application's own forms live at /auth/* without the prefix and are CSRF-protected. They are a different surface, outside this API.

Authentication¶

Organizations¶

Repositories¶

Repositories are reached through the organization that owns them; there is no account-wide list endpoint.

Activity¶

Time filters (since, until) apply to when work landed. See Activity for the two timestamps a commit carries.

Alerts¶

Webhooks¶

See Webhooks for payloads, signatures and retries.

OAuth¶

GitHub and GitLab only.

Health¶

Outside the /api prefix, and unauthenticated:

OpenAPI Documentation¶

Interactive API documentation is available at:

• Swagger UI: /docs
• OpenAPI Schema: /schema

SDK Support¶

Currently, Ospobox does not provide official SDKs. You can use any HTTP client:

import httpx

client = httpx.Client(
    base_url="http://localhost:8000/api",
    headers={"Authorization": f"Bearer {token}"}
)

orgs = client.get("/organizations/").json()

const response = await fetch('http://localhost:8000/api/organizations/', {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});
const orgs = await response.json();

curl -H "Authorization: Bearer $TOKEN" \
     http://localhost:8000/api/organizations/