HTTP API Reference

REST API for Teckel AI. This is the canonical field reference for all integrations.

Using TypeScript? The SDK wraps this API with retries, batching, and error handling.

Authentication

Authorization: Bearer tk_live_your_key_here

Get API key: Dashboard → Admin Panel → API Keys

Base URL

https://app.teckel.ai/api

Response Codes

Code	Meaning	Action
200	Success	Request accepted
400	Bad Request	Check validation errors
401	Unauthorized	Verify API key
429	Rate Limited	Implement backoff
500	Server Error	Contact support

Endpoints

POST /api/sdk/traces

Submit traces (1-100 per request).

Request:

{
  "traces": [
    {
      "query": "How do I reset my password?",
      "response": "Go to Settings → Security → Reset Password...",
      "sessionId": "chat-session-42",
      "userId": "user@example.com",
      "model": "gpt-5",
      "latencyMs": 1250,
      "systemPrompt": "You are a helpful assistant...",
      "tokens": {
        "prompt": 324,
        "completion": 89,
        "total": 413
      },
      "costUsd": 0.0042,
      "documents": [{
        "id": "password-reset-guide.md",
        "name": "Password Reset Guide",
        "text": "To reset your password, navigate to Settings...",
        "url": "https://kb.example.com/security",
        "similarity": 0.92,
        "rank": 0
      }],
      "spans": [{
        "name": "llm.complete",
        "type": "llm_call",
        "startedAt": "2025-01-15T10:00:00.000Z",
        "endedAt": "2025-01-15T10:00:01.250Z",
        "model": "gpt-5",
        "promptTokens": 324,
        "completionTokens": 89,
        "costUsd": 0.0042,
        "status": "completed"
      }],
      "metadata": {
        "ticket_ref": "SUPPORT-12345"
      }
    }
  ]
}

Trace Fields:

Field	Type	Required	Constraints	Description
query	string	Yes	1-10,000 chars	User's question
response	string	Yes	1-50,000 chars	AI's answer
traceId	string (UUID)	No	UUID v4	Trace identifier (auto-generated if omitted)
sessionId	string	No	1-200 chars	Session identifier for grouping traces
userId	string	No	1-255 chars	End-user identifier
documents	array	Recommended	Max 15	Retrieved chunks (RAG)
spans	array	No	Max 100	Spans for detailed tracing
model	string	No	1-100 chars	LLM model (e.g., "gpt-5")
latencyMs	number	No	Positive int	Response time
tokens	object	No	-	{ prompt, completion, total } - auto-calculated from spans if omitted
costUsd	number	No	Non-negative	Cost in USD (auto-calculated from tokens if omitted)
systemPrompt	string	No	1-50,000 chars	LLM system prompt
metadata	object	No	-	Custom correlation IDs

Document Fields:

Field	Type	Required	Constraints	Description
id	string	Yes	1-500 chars	Your document identifier
name	string	Yes	1-500 chars	Human-readable name
text	string	Yes	1-50,000 chars	Chunk content sent to LLM
lastUpdated	string	Recommended	ISO 8601	Last modified (for freshness analysis)
url	string	No	1-2000 chars	Link to source document
source	string	No	1-100 chars	Platform: 'confluence', 'slack', 'gdrive'
fileFormat	string	No	1-100 chars	Format: 'pdf', 'md', 'docx'
similarity	number	No	0.0-1.0	Relevance score
rank	number	No	Non-negative	Position (0 = first)
ownerEmail	string	No	Valid email	Document owner

Span Fields:

Field	Type	Required	Constraints	Description
name	string	Yes	1-500 chars	Span name
startedAt	string	Yes	ISO 8601	Start timestamp
type	string	No	See below	Span type (default: "custom")
spanId	string	No	UUID v4	Span ID (auto-generated)
parentSpanId	string	No	UUID v4	Parent span for nesting
endedAt	string	No	ISO 8601	End timestamp
durationMs	number	No	Positive int	Duration in ms
status	string	No	running, completed, error	Span status
statusMessage	string	No	1-2000 chars	Error message
model	string	No	1-100 chars	Model name (llm_call)
promptTokens	number	No	Non-negative	Input tokens
completionTokens	number	No	Non-negative	Output tokens
costUsd	number	No	Non-negative	Cost in USD for this span
toolName	string	No	1-200 chars	Tool name (tool_call)
toolArguments	object	No	Max 500KB	Tool input
toolResult	object	No	Max 500KB	Tool output
input	object	No	Max 500KB	Generic input (non-tool spans)
output	object	No	Max 500KB	Generic output (non-tool spans)
metadata	object	No	Max 10KB	Custom metadata

Span Types: llm_call, tool_call, retrieval, agent, guardrail, custom

Response:

{
  "traceIds": ["550e8400-e29b-41d4-a716-446655440000"],
  "successCount": 1
}

cURL:

curl -X POST https://app.teckel.ai/api/sdk/traces \
  -H "Authorization: Bearer tk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "traces": [{
      "query": "How do I reset my password?",
      "response": "Go to Settings → Security...",
      "sessionId": "chat-session-42",
      "model": "gpt-5"
    }]
  }'

Python:

import requests

response = requests.post(
    'https://app.teckel.ai/api/sdk/traces',
    headers={
        'Authorization': 'Bearer tk_live_your_key_here',
        'Content-Type': 'application/json'
    },
    json={
        'traces': [{
            'query': 'How do I reset my password?',
            'response': 'Go to Settings → Security...',
            'sessionId': 'chat-session-42',
            'model': 'gpt-5',
            'documents': [{
                'id': 'password-reset-guide.md',
                'name': 'Password Reset Guide',
                'text': 'To reset your password...'
            }]
        }]
    }
)

result = response.json()
print(f"Traces: {result['traceIds']}")

---

POST /api/sdk/feedback

Submit user feedback.

Request:

{
  "traceId": "550e8400-e29b-41d4-a716-446655440000",
  "type": "thumbs_down",
  "comment": "Information was outdated"
}

Field Reference:

Field	Type	Required	Description
traceId	string (UUID)	One required	Target trace
sessionId	string	One required	Target session (1-200 chars)
type	string	Yes	thumbs_up, thumbs_down, flag, rating
value	string	No	For ratings: "1" to "5"
comment	string	No	User's explanation (1-2,000 chars)

Response:

{
  "feedbackId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "createdAt": "2025-01-15T10:00:10Z"
}

Rate Limits

• 1,000 requests/hour per organization (trial), 10,000/hour (paid)
• Each trace in a batch counts toward the limit
• Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

429 Response:

{
  "error": "Rate limit exceeded",
  "retry_after": 60
}

Error Handling

Validation (400):

{
  "error": "Validation failed",
  "details": ["query: Required", "documents[0].text: Required"]
}

Authentication (401):

{
  "error": "Invalid or missing API key"
}

Size Limits

Field	Limit
query	10,000 chars
response	50,000 chars
systemPrompt	50,000 chars
documents	15 max
document.text	50,000 chars
spans	100 max
toolArguments	500 KB
toolResult	500 KB
metadata	10 KB
Total trace	3 MB
Request	100 traces, 5 MB

---

See also: TypeScript SDK | OpenTelemetry Integration