Completions

Completions API

The Completions API in the Aimable Platform enables developers to generate intelligent, context-aware responses using large language models (LLMs). It powers chat-based interactions by accepting a conversation history and returning a model-generated reply. This domain is ideal for building AI assistants, chatbots, or any application requiring natural language understanding and generation.

With support for advanced features like PII handling, file context, tool calling, and model customization, the Completions API allows fine-grained control over response behavior while maintaining compliance and security.

Key Concepts

• Chat Completion: A model-generated response based on a sequence of messages (e.g., user and assistant turns).
• Messages: The conversation history sent as an array of {role, content} objects. Roles include user, assistant, and system.
• Pseudonymization: Optional headers allow Personally Identifiable Information (PII) and Organizationally Identifiable Information (OII) to be masked or mapped for privacy.
• Context Enrichment: Use uploaded files or knowledge collections to ground responses in specific data.
• Tool Calling: Enable function/tool invocation by the model for dynamic actions like database lookups or API calls.

How to Use the Completions Endpoint

The primary endpoint for generating responses is:

POST /api-proxy/v1/chat/completions

You must include a valid bearer token in the Authorization header.

Example Request

curl -X POST 'https://platform.aimable.ai/api-proxy/v1/chat/completions' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'X-Model: gpt-4o' \
  -H 'X-Aimable-Space-Id: space_abc123' \
  -H 'X-Apply-Pii-Pseudonymization: true' \
  -H 'Content-Type: application/json' \
  -d '{
    "messages": [
      { "role": "system", "content": "You are a helpful support assistant." },
      { "role": "user", "content": "My name is John Doe and I need help with my account." }
    ],
    "temperature": 0.7,
    "max_tokens": 150,
    "stream": false
  }'

Example Response (200 OK)

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1710000000,
  "model": "gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello John, I can help you with your account. Could you please provide more details about the issue you're facing?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 32,
    "total_tokens": 57
  }
}

💡 Note: If PII pseudonymization is enabled, the response may replace John Doe with a placeholder like [NAME_1].

Common Workflows

1. Basic Chat Interaction

1. Send a conversation history using POST /v1/chat/completions
2. Include prior messages to maintain context
3. Receive a generated assistant response

2. Secure PII Handling

For applications handling sensitive data:

1. Set X-Apply-Pii-Pseudonymization: true
2. Optionally provide X-Pii-Mapping to define custom token replacements
3. The model processes anonymized content; responses are detokenized automatically

3. Tool-Augmented Responses

Enable function calling for dynamic behavior:

{
  "messages": [
    { "role": "user", "content": "What's the weather in Paris?" }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get current weather for a city",
        "parameters": {
          "type": "object",
          "properties": {
            "city": { "type": "string" }
          }
        }
      }
    }
  ],
  "tool_choice": "auto"
}

The model may respond with a tool call request, which your backend can execute and respond to.

Authentication & Error Handling

Authentication

All requests require a Bearer token:

Authorization: Bearer <your-access-token>

Without a valid token, the API returns:

{
  "detail": "Not authenticated"
}

Common Errors

| Status | Meaning | |-------|--------| | 401 | Missing or invalid access token | | 403 | Insufficient permissions for the space or action | | 422 | Invalid request structure — check detail.loc and detail.msg |

Example validation error:

{
  "detail": [
    {
      "loc": ["body", "messages"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}

Next Steps

Use the Completions API to build conversational agents with rich context, privacy controls, and extensible logic. Combine it with file uploads and tool integrations for powerful, real-world AI applications.

Related Endpoints

• POST /v1/chat/completions — Create Chat Completion