Skip to main content

​
Introduction

The Artanis REST API provides a direct HTTP interface for AI observability, enabling you to use Artanis from any programming language or environment. This is particularly useful when:
  • You’re using a language without an official SDK (e.g., Haskell, Go, Rust)
  • You need fine-grained control over HTTP requests
  • You’re integrating with existing HTTP clients or frameworks
  • You prefer not to add SDK dependencies
The REST API exposes the same endpoints that our official SDKs use internally, ensuring feature parity and reliability.

​
Base URL

All API requests should be made to: 
https://app.artanis.ai
For self-hosted deployments, use your custom base URL instead.

​
Authentication

All requests require authentication using a Bearer token in the Authorization header: 
curl -X POST https://app.artanis.ai/api/v1/traces \
  -H "Authorization: Bearer ak_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"trace_id": "trace_abc123", "name": "operation", "timestamp": "2025-12-22T10:00:00.000Z", "status": "running"}'
Get your API key from the Artanis Dashboard.

​
Required Headers

Include these headers in all requests:
HeaderValueDescription
AuthorizationBearer ak_...Your Artanis API key
Content-Typeapplication/jsonAll requests use JSON
Keep your API key secure. Never commit it to version control or expose it in client-side code.

​
Quick Example: Complete Trace

Here’s a minimal example showing how to create a complete trace with input and output: 
# 1. Generate a unique trace ID
TRACE_ID="trace_$(openssl rand -hex 11)"
TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%S.%3NZ")

# 2. Create trace
curl -X POST https://app.artanis.ai/api/v1/traces \
  -H "Authorization: Bearer ak_..." \
  -H "Content-Type: application/json" \
  -d "{\"trace_id\": \"$TRACE_ID\", \"name\": \"answer-question\", \"timestamp\": \"$TIMESTAMP\", \"status\": \"running\"}"

# 3. Record input
curl -X POST https://app.artanis.ai/api/v1/observations \
  -H "Authorization: Bearer ak_..." \
  -H "Content-Type: application/json" \
  -d "{\"trace_id\": \"$TRACE_ID\", \"type\": \"input\", \"data\": {\"question\": \"What is AI?\"}, \"timestamp\": \"$TIMESTAMP\"}"

# 4. Record output
curl -X POST https://app.artanis.ai/api/v1/observations \
  -H "Authorization: Bearer ak_..." \
  -H "Content-Type: application/json" \
  -d "{\"trace_id\": \"$TRACE_ID\", \"type\": \"output\", \"data\": \"AI stands for Artificial Intelligence\", \"timestamp\": \"$(date -u +"%Y-%m-%dT%H:%M:%S.%3NZ")\"}"

# 5. Complete trace
curl -X POST https://app.artanis.ai/api/v1/traces \
  -H "Authorization: Bearer ak_..." \
  -H "Content-Type: application/json" \
  -d "{\"trace_id\": \"$TRACE_ID\", \"name\": \"answer-question\", \"timestamp\": \"$TIMESTAMP\", \"status\": \"completed\", \"duration_ms\": 1234}"

​
Core Concepts

​
Traces

A trace represents a single operation (e.g., answering a question, classifying a ticket). Each trace:
  • Has a unique client-generated ID (format: trace_ + 22 random alphanumeric characters)
  • Starts with status: "running" and ends with status: "completed"
  • Can have associated metadata for filtering and searching

​
Observations

Observations capture the data flowing through your operation:
  • input: Data going into the operation (questions, prompts, parameters)
  • output: The final result (response, classification, answer)
  • state: Context needed for replay (document IDs, config, retrieved chunks)

​
Fire-and-Forget Pattern

The REST API follows a fire-and-forget pattern - requests are accepted and processed asynchronously. The official SDKs implement this same behavior with <0.1ms overhead.
Unlike typical REST APIs, Artanis endpoints:
  • Return immediately (typically 202 Accepted)
  • Don’t guarantee synchronous validation
  • Prioritize low latency over immediate error feedback
This design ensures observability never blocks your production application.

​
Error Handling

The API uses standard HTTP status codes:
CodeMeaningAction
202AcceptedRequest received and queued for processing
400Bad RequestCheck request format and required fields
401UnauthorizedVerify your API key is correct
413Payload Too LargeReduce data size (max ~1MB per request)
429Rate LimitedImplement exponential backoff
500Server ErrorRetry with exponential backoff
Enable debug mode in your HTTP client to see detailed error responses during development.

​
Timestamps

All timestamps must be in ISO 8601 format with millisecond precision and UTC timezone: 
2025-12-22T10:30:45.123Z

date -u +"%Y-%m-%dT%H:%M:%S.%3NZ"

​
Next Steps

Traces Endpoint

Create and complete traces

Observations Endpoint

Record inputs, outputs, and state

Feedback Endpoint

Submit user feedback for traces

Trace Search

Find traces by metadata fields