Ark APIs

ARK provides REST APIs for managing resources and executing queries. The APIs include both native ARK endpoints and OpenAI-compatible endpoints.

Interactive API Explorer

The easiest way to explore and test the APIs is through the built-in OpenAPI interface:

Start the dashboard with make dashboard or ark dashboard.

You can access the APIs using the ‘APIs’ link at bottom left of the dashboard screen:

You can also check the routes that have been setup with make routes - you will see the API routes such as ark-api.default.127.0.0.1.nip.io:8000.

You can open the API docs directly and interact with them through the path: http://ark-api.default.127.0.0.1.nip.io:8080/docs 

Authentication

ARK APIs support multiple authentication methods depending on the AUTH_MODE configuration:

• OIDC/JWT: For dashboard users (when AUTH_MODE=sso or AUTH_MODE=hybrid)
• API Keys: For service-to-service communication (when AUTH_MODE=basic or AUTH_MODE=hybrid)
• No Authentication: For development environments (when AUTH_MODE=open)

Using API Keys

For programmatic access, create API keys and use HTTP Basic Authentication:

# Create an API key (requires authentication)
curl -X POST http://localhost:8000/v1/api-keys \
  -H "Content-Type: application/json" \
  -d '{"name": "My Service Key"}'
 
# Use the API key for subsequent requests
curl -u "pk-ark-xxxxx:sk-ark-xxxxx" \
  http://localhost:8000/v1/namespaces/default/agents

See the Authentication Guide for complete configuration details.

Starting the APIs

# Development mode
make ark-api-dev
 
# Or using Docker
docker run -p 8000:8000 ark-api:latest

The APIs will be available at http://localhost:8000.

Browse the complete API documentation at http://localhost:8000/docs when the service is running.

Native ARK APIs

Standard REST APIs for managing ARK resources, for example:

• Agents: /v1/namespaces/{namespace}/agents
• Teams: /v1/namespaces/{namespace}/teams
• Queries: /v1/namespaces/{namespace}/queries
• Models: /v1/namespaces/{namespace}/models
• Evaluators: /v1/namespaces/{namespace}/evaluators
• Evaluations: /v1/namespaces/{namespace}/evaluations
• Secrets: /v1/namespaces/{namespace}/secrets
• API Keys: /v1/api-keys (for service authentication)
• Namespaces: /v1/namespaces

Standard Kubernetes REST patterns are followed, such as POST to create, DELETE to delete.

OpenAI-Compatible APIs

Use familiar OpenAI SDK patterns to interact with ARK:

List Models

curl http://localhost:8000/openai/v1/models

Returns all available agents, teams, models, and tools in OpenAI format.

Chat Completions

curl -X POST http://localhost:8000/openai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agent/my-agent",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Evaluators and Evaluations (v1)

• Base: /v1
• Evaluators:
  • GET/POST /namespaces/{namespace}/evaluators
  • GET/PUT/PATCH/DELETE /namespaces/{namespace}/evaluators/{name}
• Evaluations:
  • GET/POST /namespaces/{namespace}/evaluations
  • GET/PUT/PATCH/DELETE /namespaces/{namespace}/evaluations/{name}
  • PATCH /namespaces/{namespace}/evaluations/{name}/cancel

Examples:

List evaluators:

curl -s http://localhost:8000/v1/namespaces/default/evaluators

Create a direct evaluation (minimal):

curl -s -X POST http://localhost:8000/v1/namespaces/default/evaluations \
  -H "Content-Type: application/json" \
  -d '{
    "name": "direct-example",
    "type": "direct",
    "evaluator": {"name": "my-evaluator"},
    "config": {"input": "2+2?", "output": "4"}
  }'

For full request and response schemas, use the service OpenAPI UI at /docs when ark-api is running.

Using OpenAI SDK

from openai import OpenAI
 
client = OpenAI(
    api_key="not-needed",
    base_url="http://localhost:8000/openai/v1"
)
 
response = client.chat.completions.create(
    model="agent/my-agent",
    messages=[{"role": "user", "content": "Hello"}]
)

Model Naming

When using OpenAI endpoints, specify targets with these prefixes:

• agent/agent-name - Query an agent
• team/team-name - Query a team
• model/model-name - Query a model directly
• tool/tool-name - Query a tool