HTTP API Reference

Complete reference for integrating Teckel AI via direct HTTP requests. Use this if you're not using TypeScript/JavaScript, or if you prefer direct API calls over the SDK.

Using TypeScript? Check out the TypeScript SDK Reference for a simpler integration.

Base URL

https://app.teckel.ai/api

Authentication

All API requests require authentication via API key in Bearer token format:

Authorization: Bearer tk_live_your_key_here

Get your API key: Dashboard → Admin Panel → API Keys

Response Codes

Code	Meaning	Action
200	Success	Request accepted (processing continues asynchronously)
400	Bad Request	Check request body for validation errors
401	Unauthorized	Verify API key is correct and starts with tk_live_
403	Forbidden	Check account access permissions
429	Rate Limited	Implement exponential backoff, see rate limit headers
500	Server Error	Contact support if persistent

Endpoints

1. Start Conversation

Create or resume a conversation session.

POST /api/conversations
Authorization: Bearer tk_live_your_key_here
Content-Type: application/json

Request Body:

{
  "sessionRef": "chat_abc_123",
  "userRef": "user@example.com",
  "metadata": {
    "source": "mobile-app",
    "version": "2.1.0"
  }
}

Field	Type	Required	Description
sessionRef	string	Recommended	Conversation identifier (1-255 chars); auto-generated if not provided
userRef	string	No	Client-provided user reference (1-255 chars)
metadata	object	No	Custom context (key-value pairs)

Response:

{
  "sessionRef": "chat_abc_123",
  "createdAt": "2025-01-15T10:00:00Z"
}

cURL Example:

curl -X POST https://app.teckel.ai/api/conversations \
  -H "Authorization: Bearer tk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionRef": "chat_abc_123",
    "userRef": "user@example.com"
  }'

2. Add Trace

Record a query-response interaction.

POST /api/conversations/{sessionRef}/traces
Authorization: Bearer tk_live_your_key_here
Content-Type: application/json

Request Body (Minimal RAG Example):

{
  "query": "How do I reset my password?",
  "response": "Go to Settings → Security → Reset Password...",
  "model": "gpt-5",
  "documents": [
    {
      "documentRef": "kb-security-reset",
      "documentName": "Password Reset Guide",
      "documentText": "To reset your password, navigate to Settings...",
      "documentLastUpdated": "2025-01-15T10:00:00Z"
    }
  ]
}

Request Body (Complete Example):

{
  "query": "How do I reset my password?",
  "response": "To reset your password, go to Settings > Security...",
  "traceRef": "chat_abc_123:1",
  "model": "gpt-5",
  "responseTimeMs": 1250,
  "tokens": {
    "prompt": 324,
    "completion": 89,
    "total": 413
  },
  "documents": [
    {
      "documentRef": "kb-article-123",
      "documentName": "Password Reset Guide",
      "documentText": "To reset your password, navigate to Settings > Security...",
      "documentLastUpdated": "2025-01-15T10:00:00Z",
      "sourceUri": "https://kb.example.com/security",
      "sourceType": "confluence",
      "similarity": 0.92,
      "rank": 0,
      "ownerEmail": "docs@example.com",
      "documentType": "pdf"
    }
  ],
  "metadata": {
    "retrieval_method": "vector_search",
    "match_count": 6
  }
}

Field Reference:

Field	Type	Required	Constraints	Description
query	string	Yes	1-10,000 chars	User's question or input
response	string	Yes	1-50,000 chars	AI-generated answer
traceRef	string	Recommended	1-255 chars	Your correlation ID for this trace
documents	array	Recommended	Max 50 items	Retrieved chunks (for RAG systems)
model	string	Optional	-	LLM model identifier (e.g., "gpt-5")
responseTimeMs	number	Optional	Positive integer	End-to-end latency in milliseconds
tokens	object	Optional	See below	Token usage for cost tracking
metadata	object	Optional	Key-value pairs	Custom context/diagnostics

Document Fields:

Field	Type	Required	Constraints	Description
documentRef	string	Yes	1-255 chars	Your unique document/chunk ID
documentName	string	Yes	1-500 chars	Human-readable document name
documentText	string	Yes	1-50,000 chars	Actual chunk text sent to LLM
documentLastUpdated	string	Recommended	ISO 8601	Last modification timestamp
sourceUri	string	Optional	Valid URI	URL or file path to source
sourceType	string	Optional	-	Storage type (e.g., "confluence", "slack")
similarity	number	Optional	0.0-1.0	Vector similarity score
rank	number	Optional	Non-negative int	Position in search results (0 = first)
ownerEmail	string	Optional	Valid email	Document owner's email
documentType	string	Optional	-	File type (e.g., "pdf", "markdown")

Token Fields:

Field	Type	Required	Description
prompt	number	Yes	Input/prompt tokens consumed
completion	number	Yes	Output/completion tokens generated
total	number	Yes	Total tokens (prompt + completion)

Response:

{
  "traceRef": "chat_abc_123:1",
  "turnNumber": 1,
  "createdAt": "2025-01-15T10:00:05Z"
}

cURL Example:

curl -X POST https://app.teckel.ai/api/conversations/chat_abc_123/traces \
  -H "Authorization: Bearer tk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "How do I reset my password?",
    "response": "Go to Settings → Security → Reset Password...",
    "model": "gpt-5",
    "documents": [
      {
        "documentRef": "kb-security-reset",
        "documentName": "Password Reset Guide",
        "documentText": "To reset your password, navigate to Settings...",
        "documentLastUpdated": "2025-01-15T10:00:00Z"
      }
    ]
  }'

Python Example:

import requests

response = requests.post(
    'https://app.teckel.ai/api/conversations/chat_abc_123/traces',
    headers={
        'Authorization': 'Bearer tk_live_your_key_here',
        'Content-Type': 'application/json'
    },
    json={
        'query': 'How do I reset my password?',
        'response': 'Go to Settings → Security → Reset Password...',
        'model': 'gpt-5',
        'documents': [
            {
                'documentRef': 'kb-security-reset',
                'documentName': 'Password Reset Guide',
                'documentText': 'To reset your password, navigate to Settings...',
                'documentLastUpdated': '2025-01-15T10:00:00Z'
            }
        ]
    }
)

result = response.json()
print(f"Trace created: {result['traceRef']}")

3. Add Feedback

Record user satisfaction signal.

POST /api/conversations/{sessionRef}/feedback
Authorization: Bearer tk_live_your_key_here
Content-Type: application/json

Request Body (Thumbs Down):

{
  "type": "thumbs_down",
  "comment": "Information was outdated",
  "traceRef": "chat_abc_123:5"
}

Request Body (Rating):

{
  "type": "rating",
  "value": "4",
  "comment": "Helpful but missing some details"
}

Field Reference:

Field	Type	Required	Constraints	Description
type	string	Yes	See below	Type of feedback signal
value	string	Optional	"1"-"5"	Numeric value (only for type: "rating")
comment	string	Optional	1-5,000 chars	Free-text explanation from user
traceRef	string	Optional	1-255 chars	Link feedback to specific trace

Feedback Types:

• thumbs_up - User indicated response was helpful
• thumbs_down - User indicated response was not helpful
• flag - User flagged response for review
• rating - Numeric rating (requires value field: "1", "2", "3", "4", or "5")

Response:

{
  "status": "accepted",
  "createdAt": "2025-01-15T10:00:10Z"
}

cURL Example:

curl -X POST https://app.teckel.ai/api/conversations/chat_abc_123/feedback \
  -H "Authorization: Bearer tk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "thumbs_down",
    "comment": "Information was outdated"
  }'

4. End Conversation

Mark a conversation as completed.

PATCH /api/conversations/{sessionRef}
Authorization: Bearer tk_live_your_key_here
Content-Type: application/json

Request Body:

{
  "durationMs": 45000,
  "turnCount": 8
}

Field	Type	Required	Description
durationMs	number	No	Total conversation duration in milliseconds
turnCount	number	No	Total number of turns/traces

Response:

{
  "status": "ended",
  "sessionRef": "chat_abc_123",
  "endedAt": "2025-01-15T10:05:00Z"
}

cURL Example:

curl -X PATCH https://app.teckel.ai/api/conversations/chat_abc_123 \
  -H "Authorization: Bearer tk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "durationMs": 45000,
    "turnCount": 8
  }'

Rate Limits

Default limits:

• 1,000 requests per hour per organization
• Limit resets on the hour (e.g., 10:00:00)
• Enterprise plans available with higher limits

Response Headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1705320000

Rate Limit Exceeded Response:

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

Recommendations:

• Implement exponential backoff on 429 responses
• Monitor X-RateLimit-Remaining header
• Contact support@teckel.ai for limit increases

Error Handling

Validation Errors (400)

{
  "error": "Validation failed",
  "details": [
    "query: String must contain at least 1 character(s)",
    "documents[0].documentText: Required"
  ]
}

Authentication Errors (401)

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

Server Errors (500)

{
  "error": "Internal server error",
  "message": "Failed to process request"
}

Complete Integration Example (Python)

import requests
from typing import List, Dict, Any

class TeckelClient:
    def __init__(self, api_key: str):
        self.api_key = api_key
        self.base_url = "https://app.teckel.ai/api"
        self.headers = {
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json"
        }

    def start_conversation(self, session_ref: str, user_ref: str = None) -> Dict:
        """Start a new conversation."""
        payload = {"sessionRef": session_ref}
        if user_ref:
            payload["userRef"] = user_ref

        response = requests.post(
            f"{self.base_url}/conversations",
            headers=self.headers,
            json=payload
        )
        response.raise_for_status()
        return response.json()

    def add_trace(
        self,
        session_ref: str,
        query: str,
        response: str,
        documents: List[Dict[str, Any]] = None,
        model: str = None,
        response_time_ms: int = None
    ) -> Dict:
        """Add a trace to the conversation."""
        payload = {
            "query": query,
            "response": response
        }

        if documents:
            payload["documents"] = documents
        if model:
            payload["model"] = model
        if response_time_ms:
            payload["responseTimeMs"] = response_time_ms

        response = requests.post(
            f"{self.base_url}/conversations/{session_ref}/traces",
            headers=self.headers,
            json=payload
        )
        response.raise_for_status()
        return response.json()

    def add_feedback(
        self,
        session_ref: str,
        feedback_type: str,
        comment: str = None,
        trace_ref: str = None
    ) -> Dict:
        """Add user feedback."""
        payload = {"type": feedback_type}

        if comment:
            payload["comment"] = comment
        if trace_ref:
            payload["traceRef"] = trace_ref

        response = requests.post(
            f"{self.base_url}/conversations/{session_ref}/feedback",
            headers=self.headers,
            json=payload
        )
        response.raise_for_status()
        return response.json()

# Usage
client = TeckelClient(api_key="tk_live_your_key_here")

# Start conversation
client.start_conversation(
    session_ref="chat_123",
    user_ref="user@example.com"
)

# Add trace
result = client.add_trace(
    session_ref="chat_123",
    query="How do I reset my password?",
    response="Go to Settings → Security → Reset Password...",
    documents=[
        {
            "documentRef": "kb-security-reset",
            "documentName": "Password Reset Guide",
            "documentText": "To reset your password, navigate to Settings...",
            "documentLastUpdated": "2025-01-15T10:00:00Z"
        }
    ],
    model="gpt-5",
    response_time_ms=1250
)

print(f"Trace created: {result['traceRef']}")

# Add feedback
client.add_feedback(
    session_ref="chat_123",
    feedback_type="thumbs_up",
    trace_ref=result['traceRef']
)

Best Practices

1. Always include documentLastUpdated when available (enables freshness scoring)
2. Use consistent IDs for sessionRef and traceRef across requests
3. Include model name to enable model-level performance comparisons
4. Track response time to identify performance regressions
5. Implement retry logic with exponential backoff for 429/5xx errors
6. Monitor rate limit headers to avoid hitting limits
7. Validate input before sending to reduce 400 errors
8. End conversations when chat session completes for accurate analytics

Security Notes

• Never expose API keys in client-side code
• Use HTTPS for all requests (enforced by API)
• Rotate keys if compromised via dashboard
• Monitor usage in dashboard to detect unauthorized access
• Store keys securely using environment variables or secret management

Support

• Documentation: docs.teckel.ai
• Dashboard: app.teckel.ai
• Email: support@teckel.ai
• Getting Started: docs.teckel.ai/docs/getting-started
• TypeScript SDK: docs.teckel.ai/docs/typescript-sdk-reference