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
orAUTH_MODE=hybrid
) - API Keys: For service-to-service communication (when
AUTH_MODE=basic
orAUTH_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}
- GET/POST
- Evaluations:
- GET/POST
/namespaces/{namespace}/evaluations
- GET/PUT/PATCH/DELETE
/namespaces/{namespace}/evaluations/{name}
- PATCH
/namespaces/{namespace}/evaluations/{name}/cancel
- GET/POST
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 agentteam/team-name
- Query a teammodel/model-name
- Query a model directlytool/tool-name
- Query a tool