API Reference¶

The Carbon Connect API provides programmatic access to the Carbon Funding Navigator platform. All endpoints are served over HTTPS and return JSON responses.

Base URL¶

https://api.carbonconnect.io/api/v1

For local development:

http://localhost:8000/api/v1

Authentication¶

The API uses JWT Bearer tokens for authentication. Include the token in the Authorization header:

Authorization: Bearer <access_token>

Tokens are obtained through the Authentication endpoints. Access tokens expire after 30 minutes; refresh tokens expire after 7 days. See the Auth documentation for the full token lifecycle.

Rate Limiting¶

Rate limits are enforced per tenant to ensure fair usage across all organizations:

When a rate limit is exceeded, the API returns 429 Too Many Requests with a Retry-After header indicating the number of seconds to wait.

Error Format¶

All errors follow a consistent JSON structure:

{
  "detail": "Human-readable error message"
}

For validation errors (422), the response includes field-level detail:

{
  "detail": [
    {
      "loc": ["body", "email"],
      "msg": "value is not a valid email address",
      "type": "value_error.email"
    }
  ]
}

Standard HTTP Status Codes¶

Pagination¶

All list endpoints support cursor-based pagination with consistent parameters:

Paginated responses include metadata:

{
  "items": [...],
  "total": 150,
  "page": 1,
  "page_size": 20,
  "pages": 8
}

Multi-Tenancy¶

All authenticated requests are automatically scoped to the current user's tenant. Cross-tenant access is prevented at the middleware level. Resources created by one tenant are invisible to another.

Content Types¶

• Request body: application/json
• Response body: application/json
• Streaming endpoints: text/event-stream (SSE)
• OAuth2 login: application/x-www-form-urlencoded

Endpoint Groups¶

OpenAPI Specification¶

The full interactive API documentation is available at:

• Swagger UI: {base_url}/docs
• ReDoc: {base_url}/redoc
• OpenAPI JSON: {base_url}/openapi.json