API Endpoints¶

Complete reference for all Routstr API endpoints.

Overview¶

Routstr provides OpenAI-compatible endpoints with Bitcoin/eCash payment integration.

Base URL¶

All endpoints use the base URL:

https://api.routstr.com/v1

Authentication¶

All endpoints require authentication via:

Bearer Token: Authorization: Bearer sk-... or Authorization: Bearer cashuAeyJ0...
X-Cashu Header: X-Cashu: cashuAeyJ0... (for direct eCash payments)

See Authentication for details.

Chat¶

Create Chat Completion¶

Send messages to generate model responses.

POST /v1/chat/completions

Request Body:

{
  "model": "gpt-4",
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant."
    },
    {
      "role": "user",
      "content": "Hello!"
    }
  ],
  "temperature": 0.7,
  "stream": false
}

Parameters:

Parameter	Type	Required	Default	Description
`model`	string	Yes	-	Model ID to use
`messages`	array	Yes	-	Array of message objects
`temperature`	number	No	1.0	Sampling temperature (0-2)
`max_tokens`	integer	No	Model default	Maximum tokens to generate
`stream`	boolean	No	false	Stream partial responses
`top_p`	number	No	1.0	Nucleus sampling
`n`	integer	No	1	Number of completions
`stop`	string/array	No	null	Stop sequences
`presence_penalty`	number	No	0	Presence penalty (-2 to 2)
`frequency_penalty`	number	No	0	Frequency penalty (-2 to 2)

Response:

{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "gpt-4",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "Hello! How can I help you today?"
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 13,
    "completion_tokens": 9,
    "total_tokens": 22
  }
}

Streaming Response¶

When stream: true:

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"gpt-3.5-turbo","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"gpt-3.5-turbo","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"gpt-3.5-turbo","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

Completions (Coming Soon)¶

Create Completion¶

Note: This endpoint is coming soon and not yet available.

Generate text completion (legacy endpoint).

POST /v1/completions

Request Body:

{
  "model": "gpt-3.5-turbo-instruct",
  "prompt": "Once upon a time",
  "max_tokens": 50,
  "temperature": 0.7
}

Response:

{
  "id": "cmpl-123",
  "object": "text_completion",
  "created": 1677652288,
  "model": "gpt-3.5-turbo-instruct",
  "choices": [{
    "text": " in a faraway land, there lived a brave knight...",
    "index": 0,
    "logprobs": null,
    "finish_reason": "length"
  }],
  "usage": {
    "prompt_tokens": 4,
    "completion_tokens": 50,
    "total_tokens": 54
  }
}

Embeddings¶

Create Embeddings (Coming Soon)¶

Note: This endpoint is coming soon and not yet available.

Generate vector representations of text.

POST /v1/embeddings

Request Body:

{
  "model": "text-embedding-3-small",
  "input": "The quick brown fox jumps over the lazy dog",
  "encoding_format": "float"
}

Parameters:

Parameter	Type	Required	Default	Description
`model`	string	Yes	-	Embedding model ID
`input`	string/array	Yes	-	Text(s) to embed
`encoding_format`	string	No	"float"	Format: "float" or "base64"
`dimensions`	integer	No	Model default	Output dimensions

Response:

{
  "object": "list",
  "data": [{
    "object": "embedding",
    "index": 0,
    "embedding": [0.0023064255, -0.009327292, ...] 
  }],
  "model": "text-embedding-3-small",
  "usage": {
    "prompt_tokens": 9,
    "total_tokens": 9
  }
}

Images (Coming Soon)¶

Create Image¶

Note: This endpoint is coming soon and not yet available.

Generate images from text prompts.

POST /v1/images/generations

Request Body:

{
  "model": "dall-e-3",
  "prompt": "A white siamese cat wearing a space helmet",
  "n": 1,
  "size": "1024x1024",
  "quality": "standard"
}

Parameters:

Parameter	Type	Required	Default	Description
`model`	string	Yes	-	Model: dall-e-2, dall-e-3
`prompt`	string	Yes	-	Text description
`n`	integer	No	1	Number of images
`size`	string	No	"1024x1024"	Image dimensions
`quality`	string	No	"standard"	Quality: standard, hd
`style`	string	No	"vivid"	Style: vivid, natural
`response_format`	string	No	"url"	Format: url, b64_json

Response:

{
  "created": 1677652288,
  "data": [{
    "url": "https://generated-image-url.com/image.png",
    "revised_prompt": "A white Siamese cat wearing a detailed space helmet..."
  }]
}

Audio (Coming Soon)¶

Create Transcription¶

Note: This endpoint is coming soon and not yet available.

Convert audio to text.

POST /v1/audio/transcriptions
Content-Type: multipart/form-data

Form Data:

Field	Type	Required	Description
`file`	file	Yes	Audio file (mp3, mp4, mpeg, mpga, m4a, wav, webm)
`model`	string	Yes	Model ID (whisper-1)
`language`	string	No	Language code (ISO-639-1)
`prompt`	string	No	Context prompt
`response_format`	string	No	Format: json, text, srt, verbose_json, vtt
`temperature`	number	No	Sampling temperature

Response:

{
  "text": "Hello, this is the transcribed audio content."
}

Create Translation¶

Note: This endpoint is coming soon and not yet available.

Translate audio to English.

POST /v1/audio/translations
Content-Type: multipart/form-data

Same parameters as transcription, but always translates to English.

Models¶

List Models¶

Get available models and pricing.

GET /v1/models

Response:

{
  "object": "list",
  "data": [
    {
      "id": "gpt-3.5-turbo",
      "object": "model",
      "created": 1677610602,
      "owned_by": "openai",
      "permission": [...],
      "root": "gpt-3.5-turbo",
      "parent": null,
      "pricing": {
        "prompt": 0.001,
        "completion": 0.002,
        "unit": "1k tokens"
      }
    }
  ]
}

Wallet Management¶

Create Wallet (Coming Soon)¶

Note: This endpoint is coming soon. Currently, you can use Cashu tokens directly as API keys.

Create a new wallet with eCash deposit.

POST /v1/wallet/create

Request Body:

{
  "cashu_token": "cashuAeyJ0...",
  "admin_key": "optional-admin-key"
}

Response:

{
  "api_key": "sk-1234567890abcdef",
  "admin_key": "radmin_fedcba0987654321",
  "balance": 10000,
  "mint": "https://mint.example.com",
  "unit": "sat"
}

Check Balance¶

Get current wallet balance.

GET /v1/wallet/balance
Authorization: Bearer sk-...

Response:

{
  "balance": 8500,
  "currency": "sat",
  "reserved": 0
}

Top Up Wallet¶

Add funds to existing wallet.

POST /v1/wallet/topup
Authorization: Bearer sk-...

Request Body:

{
  "cashu_token": "cashuAeyJ0..."
}

Response:

{
  "balance": 18500,
  "amount_added": 10000,
  "currency": "sat"
}

Withdraw Funds¶

Withdraw balance as eCash.

POST /v1/wallet/withdraw
Authorization: Bearer sk-...

Request Body:

{
  "amount": 5000,
  "mint": "https://mint.example.com"
}

Response:

{
  "cashu_token": "cashuAeyJ0...",
  "amount": 5000,
  "mint": "https://mint.example.com"
}

Provider Discovery¶

Admin Settings¶

These endpoints are protected by the Admin cookie (admin_password set to your configured admin password).

Get Settings¶

GET /admin/api/settings

Returns the current application settings (sensitive values may be redacted).

Update Settings¶

PATCH /admin/api/settings
Content-Type: application/json

Body is a partial JSON of settings fields to update. Validated and persisted to the database.

List Providers¶

Get available upstream providers.

GET /v1/providers

Response:

{
  "providers": [
    {
      "name": "openai",
      "models": ["gpt-4", "gpt-3.5-turbo"],
      "endpoints": ["chat/completions", "completions"],
      "status": "active"
    }
  ]
}

Provider Info¶

Get specific provider details.

GET /v1/providers/{provider_name}

Response:

{
  "name": "openai",
  "display_name": "OpenAI",
  "description": "Official OpenAI API",
  "models": [
    {
      "id": "gpt-4",
      "name": "GPT-4",
      "context_window": 8192,
      "pricing": {
        "prompt": 0.03,
        "completion": 0.06,
        "unit": "1k tokens"
      }
    }
  ],
  "endpoints": ["chat/completions", "completions", "embeddings"],
  "features": ["streaming", "function_calling"],
  "status": "active"
}

Rate Limiting¶

All endpoints are subject to rate limiting:

Per minute: 60 requests
Per hour: 1000 requests
Per day: 10000 requests

Rate limit information is included in response headers.

Next Steps¶

Errors - Error handling reference
Authentication - Auth details
Examples - Code examples