← Back to AllCode Nexus

API Reference

Integrate AllCode Nexus programmatically using the REST API. Use these endpoints to pull metrics, manage users, and generate billing reports for your internal systems.

Authentication

All API requests require a Bearer token obtained from Amazon Cognito.

Authorization: Bearer <access_token>

Obtaining a Token

Exchange your Cognito credentials for an access token:

curl -X POST https://auth.nexus.allcode.com/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=<your_client_id>&client_secret=<your_client_secret>"

You can find your API client credentials in the Nexus portal under Settings → API Access.

Token Lifetime

Tokens are valid for 1 hour. Cache and reuse tokens until expiry to avoid unnecessary token requests.

Base URL

https://api.nexus.allcode.com/v1

Endpoints

GET /api/metrics/summary

Returns aggregated usage metrics for your organization.

Query Parameters:

Parameter Type Required Description
start_date string Yes Start date (ISO 8601, e.g., 2026-01-01)
end_date string Yes End date (ISO 8601, e.g., 2026-01-31)
group_by string No Group results by user, team, model, or day

Example Request:

curl -H "Authorization: Bearer <token>" \
  "https://api.nexus.allcode.com/v1/api/metrics/summary?start_date=2026-05-01&end_date=2026-05-27&group_by=user"

Example Response:

{
  "period": {
    "start": "2026-05-01T00:00:00Z",
    "end": "2026-05-27T23:59:59Z"
  },
  "total_input_tokens": 12450000,
  "total_output_tokens": 8320000,
  "total_requests": 4521,
  "active_users": 23,
  "breakdown": [
    {
      "user": "jane.doe@company.com",
      "input_tokens": 1250000,
      "output_tokens": 890000,
      "requests": 412
    }
  ]
}

GET /api/users

Returns a list of users in your organization with their current status and quota usage.

Query Parameters:

Parameter Type Required Description
status string No Filter by active, inactive, or all (default: all)
limit integer No Results per page (default: 50, max: 200)
offset integer No Pagination offset

Example Request:

curl -H "Authorization: Bearer <token>" \
  "https://api.nexus.allcode.com/v1/api/users?status=active&limit=10"

Example Response:

{
  "total": 45,
  "users": [
    {
      "email": "jane.doe@company.com",
      "status": "active",
      "last_active": "2026-05-27T14:32:00Z",
      "quota_policy": "Engineering Standard",
      "tokens_used_today": 523000,
      "token_limit_today": 2000000
    }
  ]
}

GET /api/billing/report

Returns billing data for cost attribution and chargeback.

Query Parameters:

Parameter Type Required Description
month string Yes Billing month (format: YYYY-MM)
format string No Response format: json (default) or csv

Example Request:

curl -H "Authorization: Bearer <token>" \
  "https://api.nexus.allcode.com/v1/api/billing/report?month=2026-05&format=json"

Example Response:

{
  "month": "2026-05",
  "organization": "Acme Corp",
  "total_cost_usd": 1247.83,
  "total_tokens": 45200000,
  "by_user": [
    {
      "email": "jane.doe@company.com",
      "input_tokens": 3200000,
      "output_tokens": 2100000,
      "cost_usd": 87.42
    }
  ],
  "by_model": [
    {
      "model": "claude-sonnet-4-20250514",
      "input_tokens": 30000000,
      "output_tokens": 20000000,
      "cost_usd": 890.00
    }
  ]
}

Error Responses

All errors follow a consistent format:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired access token"
  }
}
HTTP Status Code Description
401 UNAUTHORIZED Missing or invalid Bearer token
403 FORBIDDEN Token valid but insufficient permissions
404 NOT_FOUND Endpoint or resource not found
422 VALIDATION_ERROR Invalid query parameters
429 RATE_LIMITED Too many requests (limit: 100/minute)
500 INTERNAL_ERROR Server error — retry with backoff

Rate Limits

API requests are limited to 100 requests per minute per organization. The response includes rate limit headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1716825600

Next Steps