cURL Examples

Use cURL for quick testing, scripting, or when you don’t need an SDK. These examples work with any HTTP client.

Authentication

Include your API key in the Authorization header:

curl https://api.assisters.dev/v1/chat/completions \
  -H "Authorization: Bearer ask_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"model": "llama-3.1-8b", "messages": [{"role": "user", "content": "Hello"}]}'

Never share commands containing your API key. Use environment variables instead.

Using Environment Variables

export ASSISTERS_API_KEY="ask_your_api_key"

curl https://api.assisters.dev/v1/chat/completions \
  -H "Authorization: Bearer $ASSISTERS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "llama-3.1-8b", "messages": [{"role": "user", "content": "Hello"}]}'

Chat Completions

Basic Request

curl https://api.assisters.dev/v1/chat/completions \
  -H "Authorization: Bearer $ASSISTERS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama-3.1-8b",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "What is the capital of France?"}
    ]
  }'

Response

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1706745600,
  "model": "llama-3.1-8b",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "The capital of France is Paris."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 8,
    "total_tokens": 33
  }
}

With Parameters

curl https://api.assisters.dev/v1/chat/completions \
  -H "Authorization: Bearer $ASSISTERS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama-3.1-8b",
    "messages": [
      {"role": "user", "content": "Write a haiku about coding"}
    ],
    "temperature": 0.7,
    "max_tokens": 100,
    "top_p": 0.9
  }'

Streaming

curl https://api.assisters.dev/v1/chat/completions \
  -H "Authorization: Bearer $ASSISTERS_API_KEY" \
  -H "Content-Type: application/json" \
  -N \
  -d '{
    "model": "llama-3.1-8b",
    "messages": [{"role": "user", "content": "Tell me a short story"}],
    "stream": true
  }'

The -N flag disables buffering for streaming output.

Streaming Response

data: {"id":"chatcmpl-abc","choices":[{"delta":{"role":"assistant"}}]}

data: {"id":"chatcmpl-abc","choices":[{"delta":{"content":"Once"}}]}

data: {"id":"chatcmpl-abc","choices":[{"delta":{"content":" upon"}}]}

data: {"id":"chatcmpl-abc","choices":[{"delta":{"content":" a"}}]}

data: [DONE]

Embeddings

Single Text

curl https://api.assisters.dev/v1/embeddings \
  -H "Authorization: Bearer $ASSISTERS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "e5-large-v2",
    "input": "The quick brown fox jumps over the lazy dog"
  }'

Response

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.0023, -0.0093, 0.0158, ...]
    }
  ],
  "model": "e5-large-v2",
  "usage": {
    "prompt_tokens": 10,
    "total_tokens": 10
  }
}

Batch Embeddings

curl https://api.assisters.dev/v1/embeddings \
  -H "Authorization: Bearer $ASSISTERS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "e5-large-v2",
    "input": [
      "First document to embed",
      "Second document to embed",
      "Third document to embed"
    ]
  }'

Moderation

curl https://api.assisters.dev/v1/moderate \
  -H "Authorization: Bearer $ASSISTERS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama-guard-3",
    "input": "Hello, how are you today?"
  }'

Response

{
  "id": "modr-abc123",
  "model": "llama-guard-3",
  "results": [
    {
      "flagged": false,
      "categories": {
        "hate": false,
        "harassment": false,
        "self-harm": false,
        "sexual": false,
        "violence": false
      },
      "category_scores": {
        "hate": 0.0001,
        "harassment": 0.0002,
        "self-harm": 0.0001,
        "sexual": 0.0001,
        "violence": 0.0001
      }
    }
  ]
}

List Models

curl https://api.assisters.dev/v1/models \
  -H "Authorization: Bearer $ASSISTERS_API_KEY"

Get Single Model

curl https://api.assisters.dev/v1/models/llama-3.1-8b \
  -H "Authorization: Bearer $ASSISTERS_API_KEY"

Reranking

curl https://api.assisters.dev/v1/rerank \
  -H "Authorization: Bearer $ASSISTERS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bge-reranker-v2",
    "query": "What is machine learning?",
    "documents": [
      "Machine learning is a subset of AI.",
      "The weather today is sunny.",
      "Deep learning uses neural networks."
    ],
    "top_n": 2
  }'

Useful Options

Pretty Print JSON

Pipe to jq for formatted output:

curl https://api.assisters.dev/v1/chat/completions \
  -H "Authorization: Bearer $ASSISTERS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "llama-3.1-8b", "messages": [{"role": "user", "content": "Hi"}]}' \
  | jq .

Include Headers

Use -i to see response headers:

curl -i https://api.assisters.dev/v1/chat/completions \
  -H "Authorization: Bearer $ASSISTERS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "llama-3.1-8b", "messages": [{"role": "user", "content": "Hi"}]}'

Verbose Output

Use -v for debugging:

curl -v https://api.assisters.dev/v1/chat/completions \
  -H "Authorization: Bearer $ASSISTERS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "llama-3.1-8b", "messages": [{"role": "user", "content": "Hi"}]}'

Timeout

Set a timeout with --max-time:

curl --max-time 30 https://api.assisters.dev/v1/chat/completions \
  -H "Authorization: Bearer $ASSISTERS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "llama-3.1-8b", "messages": [{"role": "user", "content": "Hi"}]}'

Shell Scripts

Chat Function

#!/bin/bash

chat() {
  local message="$1"

  curl -s https://api.assisters.dev/v1/chat/completions \
    -H "Authorization: Bearer $ASSISTERS_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{
      \"model\": \"llama-3.1-8b\",
      \"messages\": [{\"role\": \"user\", \"content\": \"$message\"}]
    }" | jq -r '.choices[0].message.content'
}

# Usage
chat "What is 2 + 2?"

Batch Processing

#!/bin/bash

# Process each line from input file
while IFS= read -r prompt; do
  echo "Prompt: $prompt"
  echo "Response: $(chat "$prompt")"
  echo "---"
done < prompts.txt

Streaming with Processing

#!/bin/bash

# Stream and extract content
curl -sN https://api.assisters.dev/v1/chat/completions \
  -H "Authorization: Bearer $ASSISTERS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama-3.1-8b",
    "messages": [{"role": "user", "content": "Count to 10"}],
    "stream": true
  }' | while read -r line; do
    if [[ $line == data:* ]]; then
      content=$(echo "${line#data: }" | jq -r '.choices[0].delta.content // empty' 2>/dev/null)
      if [[ -n "$content" ]]; then
        printf "%s" "$content"
      fi
    fi
  done
echo ""

Common Errors

401 Unauthorized

{"error": {"message": "Invalid API key", "type": "authentication_error"}}

Check your API key is correct and not expired.

429 Rate Limited

{"error": {"message": "Rate limit exceeded", "type": "rate_limit_error"}}

Wait and retry, or upgrade your plan.

400 Bad Request

{"error": {"message": "Invalid model", "type": "invalid_request_error"}}

Check model name and request format.

Tips

Use jq

Install jq for JSON parsing: brew install jq or apt install jq

Save to File

Use -o response.json to save output to a file

Time Requests

Use time curl ... to measure latency

Test in CI

cURL is perfect for CI/CD testing and health checks

Getting Started

Guides

SDKs

Billing

Security

​cURL Examples

​Authentication

​Using Environment Variables

​Chat Completions

​Basic Request

​Response

​With Parameters

​Streaming

​Streaming Response

​Embeddings

​Single Text

​Response

​Batch Embeddings

​Moderation

​Response

​List Models

​Get Single Model

​Reranking

​Useful Options

​Pretty Print JSON

​Include Headers

​Verbose Output

​Timeout

​Shell Scripts

​Chat Function

​Batch Processing

​Streaming with Processing

​Common Errors

​401 Unauthorized

​429 Rate Limited

​400 Bad Request

​Tips

Use jq

Save to File

Time Requests

Test in CI

cURL Examples

Authentication

Using Environment Variables

Chat Completions

Basic Request

Response

With Parameters

Streaming

Streaming Response

Embeddings

Single Text

Response

Batch Embeddings

Moderation

Response

List Models

Get Single Model

Reranking

Useful Options

Pretty Print JSON

Include Headers

Verbose Output

Timeout

Shell Scripts

Chat Function

Batch Processing

Streaming with Processing

Common Errors

401 Unauthorized

429 Rate Limited

400 Bad Request

Tips