Skip to Content
ReferenceArk APIs

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:

Ark Dashboard Screenshot

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 

Ark APIs

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
Last updated on