Quickstart

Get up and running with the co-mind.ai API. This guide walks you through authentication and your first API calls.

Prerequisites

• API endpoint URL (provided by your administrator)
• User credentials (email and password)
• curl installed (or any HTTP client)

1. Health Check

   Verify the API is reachable (no authentication required):

   curl https://{BASE_URL}/health
   

   { "status": "ok" }
   
2. Authenticate

   Login with your credentials to get an access token:

   curl -X POST https://{BASE_URL}/v1/auth/login \
     -H "Content-Type: application/json" \
     -d '{
       "email": "[e-mail]",
       "password": "your_password"
     }'
   

   {
     "access_token": "eyJhbGciOiJIUzI1NiIs...",
     "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
     "token_type": "bearer",
     "expires_in": 3600
   }
   

   For long-lived programmatic access, create a Personal Access Token (PAT) instead of using short-lived JWTs.

3. List Available Models

   Check which models are deployed on your instance:

   curl https://{BASE_URL}/v1/models \
     -H "Authorization: Bearer YOUR_TOKEN"
   

   {
     "object": "list",
     "data": [
       { "id": "Qwen/Qwen2.5-32B-Instruct", "object": "model", "owned_by": "vllm" },
       { "id": "llama3.2:3b", "object": "model", "owned_by": "ollama" }
     ]
   }
   
4. Send a Chat Completion

   Make your first chat request using one of the available models:

   curl -X POST https://{BASE_URL}/v1/chat/completions \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "model": "MODEL_ID_FROM_STEP_3",
       "messages": [
         {"role": "user", "content": "What is the capital of France?"}
       ]
     }'
   

   {
     "id": "chatcmpl-abc123",
     "object": "chat.completion",
     "choices": [
       {
         "index": 0,
         "message": {
           "role": "assistant",
           "content": "The capital of France is Paris."
         },
         "finish_reason": "stop"
       }
     ],
     "usage": {
       "prompt_tokens": 14,
       "completion_tokens": 8,
       "total_tokens": 22
     }
   }
   
5. Stream a Response

   Enable streaming to receive tokens as they’re generated:

   curl -X POST https://{BASE_URL}/v1/chat/completions \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "model": "MODEL_ID",
       "messages": [
         {"role": "user", "content": "Write a haiku about AI"}
       ],
       "stream": true
     }'
   

   data: {"id":"chatcmpl-abc","choices":[{"delta":{"role":"assistant"},"index":0}]}
   
   data: {"id":"chatcmpl-abc","choices":[{"delta":{"content":"Silicon"},"index":0}]}
   
   data: {"id":"chatcmpl-abc","choices":[{"delta":{"content":" dreams"},"index":0}]}
   
   data: [DONE]
   
6. Check Backend Capabilities

   See which features each backend supports:

   curl https://{BASE_URL}/v1/capabilities \
     -H "Authorization: Bearer YOUR_TOKEN"
   

   This returns which backends support chat, embeddings, vision, tool calling, and streaming.

Troubleshooting

401 Unauthorized

Your token is missing, expired, or invalid. Re-authenticate with POST /v1/auth/login or check your PAT hasn’t been revoked.

403 Forbidden

Your token doesn’t have the required scope. Check the scopes assigned to your PAT with GET /v1/api-tokens/scopes.

404 Not Found

Check the endpoint URL and ensure {BASE_URL} is correct. All API endpoints use the /v1/ prefix.

409 Conflict

The model doesn’t support the requested capability (e.g., vision on a text-only model). Check capabilities with GET /v1/capabilities.

429 Rate Limited

Too many requests. Wait and retry with exponential backoff.

What’s Next?

Authentication

JWT vs PAT, SSO, token refresh, and security best practices.

API Tokens

Create scoped tokens for programmatic access.

Developer Guide

Complete endpoint reference with all API areas.

API Reference

Full auto-generated API documentation.