Stored Completions

The Stored Completions API lets you:

List: browse stored completions with filtering by model, metadata, and pagination.
Retrieve: get the full details of a specific completion including usage and parameters.
Update: attach or modify metadata on stored completions for tagging and organization.
Delete: remove stored completions you no longer need.
Messages: retrieve the full message history (input and output) for a completion.

All endpoints require API key authentication and are scoped to the authenticated project and to the workspace the request resolves to (see Workspace scope). Completions are stored using the platform's standard two-tier storage architecture. For details on storage tiers, encryption, retention, and billing, see Storage.

// scopeWorkspace scope

A stored completion belongs to the workspace its create request resolved to: the ws_ path prefix, else the X-Workspace-Id header, else the only workspace of an API key confined to one, else the project's default workspace. Every endpoint on this page resolves the workspace the same way and reaches only that workspace's completions. A completion in another workspace answers 404 completion_not_found, exactly as a missing one does.

An API key confined to some of the project's workspaces reaches only those. Naming another returns 403 Forbidden (workspace_not_allowed), and a key confined to several workspaces must name one. See Authentication & Security.
The project's default workspace is never an operational workspace: making one the default is refused with 400 Bad Request (operational_default_forbidden). In a project with no default workspace, a key that belongs to a user must name a workspace; a request that names none returns 403 Forbidden (workspace_required). A key with no user behind it reaches every completion of the project there.
Completions stored before completions recorded their workspace belong to none. Only a key with no user behind it and no workspace list reaches them, whichever workspace the request names. A confined key never does, and neither does a key that belongs to a user: nothing shows such a completion lies in a workspace that user can read.

List Completions

GET /{project_id}/{endpoint_slug}/v1/chat/completions

Returns a paginated list of the stored completions of the workspace the request resolves to (see Workspace scope).

// queryQuery parameters

Parameter	Type	Description
afteroptional	string	Cursor for pagination. Pass the `id` of the last item from the previous page.
limitoptional	integer	Maximum number of completions to return (1-100, default 20).
orderoptional	string	Sort order: `"asc"` or `"desc"` (default `"desc"`).
modeloptional	string	Filter by model name.
metadata[key]optional	string	Filter by metadata key-value pair. Example: `metadata[env]=production`.

curl

                    curl "https://api.erebine.ai/proj_ABC123/my-endpoint/v1/chat/completions?limit=5&order=desc&model=llama3-8b" \
  -H "Authorization: Bearer ere_myproject_your_api_key"
                

Response

                        {
  "object": "list",
  "data": [
    {
      "id": "chatcmpl-abc123",
      "object": "chat.completion",
      "created": 1700000000,
      "model": "llama3-8b",
      "choices": [
        {
          "index": 0,
          "message": {
            "role": "assistant",
            "content": "Hello! How can I help you today?"
          },
          "finish_reason": "stop"
        }
      ],
      "usage": {
        "prompt_tokens": 12,
        "completion_tokens": 9,
        "total_tokens": 21
      },
      "metadata": {"env": "production"},
      "service_tier": "default",
      "system_fingerprint": "fp_abc123"
    }
  ],
  "first_id": "chatcmpl-abc123",
  "last_id": "chatcmpl-abc123",
  "has_more": true
}
                    

Get Completion

GET /{project_id}/{endpoint_slug}/v1/chat/completions/{id}

Retrieves a single stored completion by its ID, including full usage details and request parameters.

When the model returned reasoning, the stored assistant message carries it on reasoning and reasoning_content (identical text), the same shape as the original response. A completion with no reasoning omits both fields.

curl

                    curl https://api.erebine.ai/proj_ABC123/my-endpoint/v1/chat/completions/chatcmpl-abc123 \
  -H "Authorization: Bearer ere_myproject_your_api_key"
                

Response

                        {
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1700000000,
  "model": "llama3-8b",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 9,
    "total_tokens": 21,
    "prompt_tokens_details": null,
    "completion_tokens_details": null
  },
  "metadata": {},
  "service_tier": "default",
  "system_fingerprint": "fp_abc123",
  "request_id": "req_xyz789",
  "temperature": 0.7,
  "top_p": 1.0,
  "presence_penalty": 0.0,
  "frequency_penalty": 0.0
}
                    

Update Completion

POST /{project_id}/{endpoint_slug}/v1/chat/completions/{id}

Updates the metadata on a stored completion. Use this to tag or annotate completions for later filtering.

// bodyRequest body

Parameter	Type	Description
metadatarequired	object	Key-value pairs to set on the completion. Replaces existing metadata.

curl

                    curl -X POST https://api.erebine.ai/proj_ABC123/my-endpoint/v1/chat/completions/chatcmpl-abc123 \
  -H "Authorization: Bearer ere_myproject_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "env": "production",
      "team": "nlp",
      "reviewed": "true"
    }
  }'
                

Response

Returns the updated completion object (same format as Get Completion).

Delete Completion

DELETE /{project_id}/{endpoint_slug}/v1/chat/completions/{id}

Permanently deletes a stored completion and its associated messages.

curl

                    curl -X DELETE https://api.erebine.ai/proj_ABC123/my-endpoint/v1/chat/completions/chatcmpl-abc123 \
  -H "Authorization: Bearer ere_myproject_your_api_key"
                

Response

                        {
  "id": "chatcmpl-abc123",
  "object": "chat.completion.deleted",
  "deleted": true
}
                    

Get Messages

GET /{project_id}/{endpoint_slug}/v1/chat/completions/{id}/messages

Retrieves the full message history for a stored completion, including both the input messages (system, user, tool) and the assistant response.

Each message item carries an object field set to "chat.completion.message", plus the required id, role, and content fields. Optional fields name, tool_calls, and tool_call_id are included when present (tool messages always carry tool_call_id; assistant messages that invoked tools carry tool_calls). An assistant message whose response included reasoning carries it on reasoning and reasoning_content.

// queryQuery parameters

Parameter	Type	Description
afteroptional	string	Cursor for pagination.
limitoptional	integer	Maximum messages to return (default 20).
orderoptional	string	Sort order: `"asc"` (default) or `"desc"`.

curl

                    curl "https://api.erebine.ai/proj_ABC123/my-endpoint/v1/chat/completions/chatcmpl-abc123/messages?order=asc" \
  -H "Authorization: Bearer ere_myproject_your_api_key"
                

Response

                        {
  "object": "list",
  "data": [
    {
      "id": "msg_001",
      "object": "chat.completion.message",
      "role": "system",
      "content": "You are a helpful assistant."
    },
    {
      "id": "msg_002",
      "object": "chat.completion.message",
      "role": "user",
      "content": "Hello!"
    },
    {
      "id": "msg_003",
      "object": "chat.completion.message",
      "role": "assistant",
      "content": "Hello! How can I help you today?"
    }
  ],
  "first_id": "msg_001",
  "last_id": "msg_003",
  "has_more": false
}
                    

Client Examples

// pythonPython (requests)

Python

                    import requests

headers = {
    "Authorization": "Bearer ere_myproject_your_api_key",
    "Content-Type": "application/json"
}
base = "https://api.erebine.ai/proj_ABC123/my-endpoint/v1"

# List stored completions
completions = requests.get(
    f"{base}/chat/completions?limit=5&order=desc",
    headers=headers
).json()
for c in completions["data"]:
    print(f"{c['id']} - {c['model']} ({c['usage']['total_tokens']} tokens)")

# Get a specific completion
comp = requests.get(
    f"{base}/chat/completions/chatcmpl-abc123",
    headers=headers
).json()
print(f"Model: {comp['model']}, Finish: {comp['choices'][0]['finish_reason']}")

# Update completion metadata
requests.post(
    f"{base}/chat/completions/chatcmpl-abc123",
    headers=headers,
    json={
        "metadata": {
            "env": "production",
            "reviewed": "true"
        }
    }
)

# Get completion messages
messages = requests.get(
    f"{base}/chat/completions/chatcmpl-abc123/messages?order=asc",
    headers=headers
).json()
for msg in messages["data"]:
    print(f"[{msg['role']}] {msg['content']}")

# Delete a completion
requests.delete(
    f"{base}/chat/completions/chatcmpl-abc123",
    headers=headers
)
                

// nodeNode.js (fetch)

JavaScript

                    const base = "https://api.erebine.ai/proj_ABC123/my-endpoint/v1";
const headers = {
    "Authorization": "Bearer ere_myproject_your_api_key",
    "Content-Type": "application/json"
};

// List stored completions
const listRes = await fetch(
    `${base}/chat/completions?limit=5&order=desc`,
    { headers }
);
const completions = await listRes.json();
completions.data.forEach(c =>
    console.log(`${c.id} - ${c.model} (${c.usage.total_tokens} tokens)`)
);

// Get a specific completion
const compRes = await fetch(
    `${base}/chat/completions/chatcmpl-abc123`,
    { headers }
);
const comp = await compRes.json();
console.log(`Model: ${comp.model}`);

// Update completion metadata
await fetch(`${base}/chat/completions/chatcmpl-abc123`, {
    method: "POST",
    headers,
    body: JSON.stringify({
        metadata: { env: "production", reviewed: "true" }
    })
});

// Get completion messages
const msgsRes = await fetch(
    `${base}/chat/completions/chatcmpl-abc123/messages?order=asc`,
    { headers }
);
const messages = await msgsRes.json();
messages.data.forEach(msg =>
    console.log(`[${msg.role}] ${msg.content}`)
);

// Delete a completion
await fetch(`${base}/chat/completions/chatcmpl-abc123`, {
    method: "DELETE",
    headers
});
                

Error Handling

Error responses currently use the envelope type values invalid_request_error for 4xx (including 404 resource lookups) and internal_error for 5xx. These envelope type strings are tracked for alignment with the OpenAI spec (not_found_error, server_error) in a future release.

json

                    {
  "error": {
    "type": "invalid_request_error",
    "code": "completion_not_found",
    "message": "Completion 'chatcmpl-abc123' does not exist or does not belong to this project.",
    "param": null
  }
}
                

// codesStatus codes

HTTP Status	Error Code	Description
400	`invalid_request`	Missing or invalid parameters.
401	`authentication_error`	Invalid or missing API key.
403	`workspace_not_allowed`	The request names a workspace outside the API key's workspace list, or a key confined to several workspaces names none. See Workspace scope.
403	`workspace_not_in_project`	The `ws_` path prefix or `X-Workspace-Id` header does not name a workspace of the project.
403	`workspace_required`	The project has no default workspace and the request, made with a key that belongs to a user, names none. See Workspace scope.
404	`completion_not_found`	The specified completion ID does not exist in your project, or belongs to another workspace than the one the request resolves to.
429	`rate_limit_exceeded`	Too many requests. Check the `Retry-After` header.
500	`internal_error`	Server-side failure. Retry the request.