AIOps Bot Platform
Console

Projects API

Project-scoped management for agents and resources

Projects API

This API provides project-scoped management for agents, API key overrides, priority conversations, and usage analytics.

Interactive Documentation

open_in_new View Interactive API Documentation

Overview

The Projects API allows you to manage project resources programmatically. All endpoints require a project API key that is scoped to a specific project.

Key Features

  • Agent Management: Create, list, update, and delete agents
  • API Key Overrides: Custom LLM API keys for specific conversations
  • Custom LLMs: Project-scoped Bring-Your-Own LLM endpoints (secret-backed)
  • Priority Conversations: Mark conversations as high-priority to bypass failover
  • Usage Analytics: Token usage and BOB credits tracking
  • Bootstrap Tokens: Issue single-use tokens for agent initialization

Authentication

All endpoints require a valid project API key in the Authorization header:

Authorization: Bearer bpk_<your_api_key>

Project API keys are created via the admin dashboard and are project-scoped.

Endpoints

Agent Management

Create Agent

POST /api/projects/{projectId}/agents

Create a new agent and receive a bootstrap token for authentication.

Request:

{
  "name": "Customer Support Bot",
  "description": "Handles tier 1 support queries",
  "user": {
    "email": "customer@example.com",
    "name": "Customer X"
  }
}

Response:

{
  "agent": {
    "id": "agent-123",
    "name": "Customer Support Bot",
    "description": "Handles tier 1 support queries",
    "status": "active",
    "user": {
      "email": "customer@example.com",
      "name": "Customer X"
    },
    "projectId": "proj-456",
    "createdAt": "2024-01-01T00:00:00Z"
  },
  "bootstrapToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

List Agents

GET /api/projects/{projectId}/agents
GET /api/projects/{projectId}/agents?emails=user1@example.com,user2@example.com

List all agents for the project, optionally filtered by user email.

Get Agent

GET /api/projects/{projectId}/agents/{agentId}

Get a single agent by ID.

Update Agent

PATCH /api/projects/{projectId}/agents/{agentId}

Update agent name, description, or status.

Request:

{
  "status": "inactive"
}

Delete Agent

DELETE /api/projects/{projectId}/agents/{agentId}

Delete an agent and revoke all its tokens.

API Key Overrides

Create Override

POST /api/projects/{projectId}/api-key-overrides

Create an API key override for a specific conversation and model.

Request:

{
  "conversationId": "conv-123",
  "modelId": "qwen-qwq-32b",
  "apiKey": "sk-1234567890abcdef",
  "notes": "Customer X's API key"
}

Benefits:

  • Bypasses project request limits
  • Uses custom API key instead of platform default
  • Usage tracked separately with isOverrideKey flag

List Overrides

GET /api/projects/{projectId}/api-key-overrides

List all API key overrides for the project.

Get Override

GET /api/projects/{projectId}/api-key-overrides/{conversationId}/{modelId}

Get a specific override by conversation and model ID.

Update Override

PUT /api/projects/{projectId}/api-key-overrides/{conversationId}/{modelId}

Update API key or notes.

Delete Override

DELETE /api/projects/{projectId}/api-key-overrides/{conversationId}/{modelId}

Delete an API key override.

Custom LLMs

Project-scoped Bring-Your-Own LLM endpoints. Each enabled backend appears in the project's model catalog prefixed with custom: (e.g. custom:acme-gpt) and routes chat requests to your own endpoint using your own credentials. Requests bypass the project request limit. See Secrets & Vaults and Models & routing.

Create Custom LLM

POST /api/projects/{projectId}/custom-llms

Provide either a raw apiKey or a secretId referencing a project secret.

Request (with a secret):

{
  "profileName": "acme-gpt",
  "model": "gpt-4o",
  "apiBase": "https://api.example.com/v1",
  "secretId": "<project secret id>",
  "authScheme": "bearer"
}

Request (with a raw key):

{
  "profileName": "acme-gpt",
  "model": "gpt-4o",
  "apiBase": "https://api.example.com/v1",
  "apiKey": "sk-1234567890abcdef",
  "authScheme": "bearer"
}

Response (201):

{
  "customLlm": {
    "id": "cllm-123",
    "projectId": "proj-456",
    "profileName": "acme-gpt",
    "modelId": "custom:acme-gpt",
    "model": "gpt-4o",
    "apiBase": "https://api.example.com/v1",
    "apiKeyMasked": null,
    "secretId": "secret-789",
    "secretName": "OpenAI Production Key",
    "provider": null,
    "authScheme": "bearer",
    "enabled": true,
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z"
  }
}
  • profileName must match ^[a-z0-9][a-z0-9-_]*$.
  • authScheme is bearer (default) or apikey.
  • Selecting a secretId clears any raw key; sending apiKey clears the secret link.

List Custom LLMs

GET /api/projects/{projectId}/custom-llms

Get Custom LLM

GET /api/projects/{projectId}/custom-llms/{id}

Update Custom LLM

PUT /api/projects/{projectId}/custom-llms/{id}

Any subset of fields. Send apiKey to switch to a raw key (clears the secret), or secretId to switch to a secret (clears the raw key).

Delete Custom LLM

DELETE /api/projects/{projectId}/custom-llms/{id}

Priority Conversations

Create Priority

POST /api/projects/{projectId}/priority-conversations

Mark a conversation as priority to bypass latency-based failover.

Request:

{
  "conversationId": "conv-important-123",
  "description": "VIP customer conversation"
}

List Priorities

GET /api/projects/{projectId}/priority-conversations

List all priority conversations.

Delete Priority

DELETE /api/projects/{projectId}/priority-conversations/{priorityId}

Remove priority status from a conversation.

Usage Analytics

Get BOB Usage

GET /api/projects/{projectId}/bob-usage?startDate=2024-01-01&endDate=2024-01-31

Get token usage statistics for BOB API calls.

Response:

{
  "usage": [
    {
      "apiKey": "bpk_xxx",
      "totalCredits": 1000,
      "requestCount": 50
    }
  ]
}

Security

  • API Key Encryption: All override API keys are encrypted at rest with AES-256-GCM
  • Project Scoping: API keys are scoped to a specific project
  • Token Rotation: Bootstrap tokens are single-use and expire after 5 minutes
  • Audit Logging: All operations are logged for audit purposes

Access Control

API keys are scoped to a specific project. All operations are restricted to that project only.

Next Steps