Nexus API Reference

Full endpoint documentation for creating, reading, updating, and deleting projects, plus unified resource overview.

Authentication

All endpoints require authentication via Authorization: Bearer YOUR_API_KEY header.

Project context is automatically determined from your API key. No project_id query parameter needed.

Endpoints

POST /v1/projects

Create a new project namespace.

Request body:

{
  "name": "Production",
  "description": "Live environment resources"
}

Parameters:

• name (required, string, 1-100 chars) — Human-readable project name
• description (optional, string, max 500 chars) — Project description

Response (201 Created):

{
  "id": "proj_abc123...",
  "name": "Production",
  "slug": "production",
  "description": "Live environment resources",
  "created_at": "2026-02-10T12:00:00Z",
  "updated_at": "2026-02-10T12:00:00Z"
}

Example:

curl -X POST "https://api.solenoid.systems/v1/projects" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Production","description":"Live environment"}'

GET /v1/projects

List all projects for your account with cursor-based pagination.

Query parameters:

• limit (optional, integer, 1-100, default: 10) — Number of projects to return
• cursor (optional, string) — Pagination cursor from previous response

Response (200 OK):

{
  "projects": [
    {
      "id": "proj_default...",
      "name": "Default",
      "slug": "default",
      "description": null,
      "created_at": "2026-01-15T10:00:00Z"
    },
    {
      "id": "proj_abc123...",
      "name": "Production",
      "slug": "production",
      "description": "Live environment",
      "created_at": "2026-02-10T12:00:00Z"
    }
  ],
  "cursor": "eyJpZCI6InByb2pfYWJjMTIzIn0"
}

Example:

curl "https://api.solenoid.systems/v1/projects?limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET /v1/projects/:id

Get details of a specific project by ID.

Path parameters:

• id (required, string) — Project ID (proj_…)

Response (200 OK):

{
  "id": "proj_abc123...",
  "name": "Production",
  "slug": "production",
  "description": "Live environment resources",
  "created_at": "2026-02-10T12:00:00Z",
  "updated_at": "2026-02-10T12:00:00Z"
}

Example:

curl "https://api.solenoid.systems/v1/projects/proj_abc123..." \
  -H "Authorization: Bearer YOUR_API_KEY"

PATCH /v1/projects/:id

Update project name and/or description. Slug is immutable.

Path parameters:

• id (required, string) — Project ID to update

Request body:

{
  "name": "Production (US)",
  "description": "US region production environment"
}

Parameters:

• name (optional, string, 1-100 chars) — New project name
• description (optional, string or null, max 500 chars) — New description (null to remove)

Response (200 OK):

{
  "id": "proj_abc123...",
  "name": "Production (US)",
  "slug": "production",
  "description": "US region production environment",
  "updated_at": "2026-02-10T14:00:00Z"
}

Example:

curl -X PATCH "https://api.solenoid.systems/v1/projects/proj_abc123..." \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Production (US)"}'

DELETE /v1/projects/:id

Soft-delete a project and enqueue async resource cleanup across all products.

Path parameters:

• id (required, string) — Project ID to delete

Response (200 OK):

{
  "success": true,
  "deleted_at": "2026-02-10T15:00:00Z"
}

Example:

curl -X DELETE "https://api.solenoid.systems/v1/projects/proj_abc123..." \
  -H "Authorization: Bearer YOUR_API_KEY"

Important:

• Cannot delete the default project unless you have at least one other active project
• Resources become immediately inaccessible (404 on access attempts)
• Full purge happens asynchronously with retry semantics
• Deletion is permanent after background cleanup completes

GET /v1/projects/:id/overview

Get aggregated resource counts and usage metrics for a project across all products.

Path parameters:

• id (required, string) — Project ID to get overview for

Response (200 OK):

{
  "project_id": "proj_abc123...",
  "project_name": "Production",
  "resources": {
    "flags": 12,
    "monitors": 3,
    "relays": 5,
    "buckets": 2,
    "keys": 4,
    "locks": 1,
    "chains": 0,
    "meters": 8
  },
  "usage": {
    "meter_balance": 10000,
    "last_activity": "2026-02-10T12:05:00Z"
  }
}

Example:

curl "https://api.solenoid.systems/v1/projects/proj_abc123.../overview" \
  -H "Authorization: Bearer YOUR_API_KEY"

Performance:

• Results cached for 5 minutes in KV
• Safe for dashboard polling
• Sub-second response time after initial cache

Pagination

All list endpoints use cursor-based pagination:

1. Make initial request with optional limit parameter
2. Response includes cursor field if more results exist
3. Pass cursor in next request: ?cursor=eyJpZCI6InByb2pfYWJjMTIzIn0
4. Repeat until cursor field is absent

Project Isolation

Resources are automatically scoped to the project associated with your API key. No project_id query parameter needed.

To access resources in a different project:

1. Create an API key scoped to that project via /v1/keys
2. Use the new key in your Authorization header
3. All requests now target the new project

Error Codes

See Errors for detailed error documentation.

Common errors:

• validation_error (400) — Invalid request parameters
• unauthorized (401) — Missing or invalid API key
• forbidden (403) — Cannot delete default project or access deleted project
• not_found (404) — Project doesn’t exist or is deleted
• conflict (409) — Slug collision (auto-resolved with -N suffix)
• rate_limit_exceeded (429) — Too many requests