API Reference

Complete reference for the AVCodex Chat Completions endpoint.

Endpoint#

code

POST https://app.avcodex.com/api/v1/chat/completions

Request#

Headers#

Header	Required	Description
`Authorization`	Yes	`Bearer YOUR_API_KEY`.
`Content-Type`	Yes	`application/json`.
`X-Chat-Session-ID`	No	Alternative session ID.
`X-Correlation-ID`	No	Request tracking ID.

Body#

typescript

{
  model: string;          // Your agent's appNameId (e.g., "myagent-123")
  messages: Array<{
    role: "user" | "assistant" | "system";
    content: string;
  }>;
  stream?: boolean;       // Default: false
  chatSessionId?: string; // Continue conversation
}

Parameters#

model: your AVCodex agent's appNameId (format: agentname-123).
messages: array of message objects.
stream: enable streaming (optional).
chatSessionId: continue an existing session (optional).

Response#

Success (200)#

json

{
  "chatSessionId": "550e8400-e29b-41d4-a716-446655440000",
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1699451234,
  "model": "myagent-123",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "Response text"
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 15,
    "total_tokens": 25
  }
}

Error format#

All errors return a JSON object with an error field:

json

{
  "error": "Error message describing the issue"
}

Status codes#

Code	Description
200	Success.
400	Invalid request parameters.
401	Authentication / authorization failure.
404	Unknown model (agent).
500	Server error.

Common errors#

#### Invalid request (400)

json

{
  "error": "`model` is required and must be a string"
}

json

{
  "error": "`messages` must be a non-empty array"
}

#### Authentication failed (401)

json

{
  "error": "Missing API key"
}

json

{
  "error": "Invalid API key"
}

json

{
  "error": "This API is only available on a paid plan.  Visit your dashboard to upgrade."
}

#### Model not found (404)

json

{
  "error": "Unknown model \"invalidagent-999\""
}

#### Server errors (500)

json

{
  "error": "Internal Server Error"
}

Sessions#

New session#

Omit chatSessionId to start fresh.

Continue session#

Include chatSessionId from the previous response. Previous messages are loaded automatically.

Requirements#

Builder plan or higher (free accounts cannot access the API).
Valid API key from your agent's Share tab.

*AVCodex · Your AV expertise. Amplified by AI.*