mirror of https://github.com/Routstr/routstr-core.git synced 2026-08-09 11:04:36 +00:00

Files

T

Cursor Agentanddb2002dominic d4c1389249 docs: Add comprehensive documentation for Routstr Core project

Co-authored-by: db2002dominic <db2002dominic@gmail.com>

2025-08-25 01:17:40 +00:00

11 KiB

Raw Blame History

API Endpoints

Complete reference for all available endpoints in Routstr Core.

Chat Completions

Create Chat Completion

Generate a model response for a conversation.

POST /v1/chat/completions

Request Body:

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

Parameters:

Parameter	Type	Required	Default	Description
`model`	string	Yes	-	Model ID to use
`messages`	array	Yes	-	Conversation messages
`temperature`	number	No	1.0	Sampling temperature (0-2)
`max_tokens`	integer	No	Unlimited	Maximum tokens to generate
`stream`	boolean	No	false	Stream response
`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)
`logit_bias`	object	No	null	Token bias
`user`	string	No	null	End-user identifier

Response:

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

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

Create Completion

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

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

Create Image

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

Create Transcription

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

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": 1677652288,
      "owned_by": "openai",
      "pricing": {
        "prompt": 0.0015,
        "completion": 0.002,
        "prompt_sats_per_1k": 3,
        "completion_sats_per_1k": 4
      }
    },
    {
      "id": "gpt-4",
      "object": "model",
      "created": 1677652288,
      "owned_by": "openai",
      "pricing": {
        "prompt": 0.03,
        "completion": 0.06,
        "prompt_sats_per_1k": 60,
        "completion_sats_per_1k": 120
      }
    }
  ]
}

Get Model

Get details for a specific model.

GET /v1/models/{model_id}

Response:

{
  "id": "gpt-3.5-turbo",
  "object": "model",
  "created": 1677652288,
  "owned_by": "openai",
  "permission": [{
    "allow_create_engine": false,
    "allow_sampling": true,
    "allow_logprobs": true,
    "allow_search_indices": false,
    "allow_view": true,
    "allow_fine_tuning": false
  }],
  "root": "gpt-3.5-turbo",
  "parent": null,
  "pricing": {
    "prompt": 0.0015,
    "completion": 0.002,
    "image": 0,
    "request": 0
  }
}

Wallet Management

Create API Key

Create a new API key with eCash deposit.

POST /v1/wallet/create

Request Body:

{
  "cashu_token": "cashuAeyJ0b2tlbiI6W3...",
  "name": "My API Key",
  "expires_at": "2024-12-31T23:59:59Z",
  "refund_npub": "npub1..."
}

Response:

{
  "api_key": "rstr_1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p",
  "balance": 10000,
  "created_at": "2024-01-01T00:00:00Z",
  "expires_at": "2024-12-31T23:59:59Z"
}

Check Balance

Get current balance and usage stats.

GET /v1/wallet/balance
Authorization: Bearer {api_key}

Response:

{
  "balance": 8546,
  "total_deposited": 10000,
  "total_spent": 1454,
  "last_used": "2024-01-01T12:34:56Z",
  "created_at": "2024-01-01T00:00:00Z"
}

Top Up Balance

Add funds to existing API key.

POST /v1/wallet/topup
Authorization: Bearer {api_key}

Request Body:

{
  "cashu_token": "cashuAeyJ0b2tlbiI6W3..."
}

Response:

{
  "old_balance": 8546,
  "added_amount": 5000,
  "new_balance": 13546
}

Withdraw Balance

Generate eCash token from balance.

POST /v1/wallet/withdraw
Authorization: Bearer {api_key}

Request Body:

{
  "amount": 5000,
  "mint_url": "https://mint.minibits.cash/Bitcoin"
}

Response:

{
  "cashu_token": "cashuAeyJ0b2tlbiI6W3...",
  "amount": 5000,
  "mint_url": "https://mint.minibits.cash/Bitcoin"
}

Node Information

Get Node Info

Get public information about the Routstr node.

GET /v1/info

Response:

{
  "name": "Lightning AI Gateway",
  "description": "Fast AI API access with Bitcoin payments",
  "version": "0.1.1b",
  "npub": "npub1abc...",
  "mints": [
    "https://mint.minibits.cash/Bitcoin",
    "https://testnut.cashu.space"
  ],
  "http_url": "https://api.lightning-ai.com",
  "onion_url": "http://lightningai.onion",
  "models": {
    "gpt-3.5-turbo": {
      "name": "GPT-3.5 Turbo",
      "pricing": {
        "prompt": 0.0015,
        "completion": 0.002
      }
    }
  }
}

Discovery

List Providers

Discover Routstr providers from Nostr relays.

GET /v1/providers

Query Parameters:

Parameter	Type	Description
`relay`	string	Specific relay URL
`limit`	integer	Maximum results

Response:

{
  "providers": [
    {
      "name": "Fast AI Node",
      "npub": "npub1xyz...",
      "url": "https://fast-ai.com",
      "description": "Low latency AI API access",
      "models": ["gpt-3.5-turbo", "gpt-4"],
      "pricing": {
        "gpt-3.5-turbo": {
          "prompt_sats_per_1k": 3,
          "completion_sats_per_1k": 4
        }
      }
    }
  ]
}

Admin Endpoints

Admin Dashboard

Access the web-based admin interface.

GET /admin/

Requires password authentication via web form.

Admin API

Protected endpoints for node management.

POST /admin/api/withdraw
X-Admin-Password: {admin_password}

Request Body:

{
  "api_key": "rstr_123...",
  "amount": 5000
}

Health & Status

Health Check

Monitor service health.

GET /health

Response:

{
  "status": "healthy",
  "version": "0.1.1b",
  "timestamp": "2024-01-01T00:00:00Z",
  "checks": {
    "database": "ok",
    "upstream": "ok",
    "mint": "ok"
  }
}

Metrics

Get service metrics.

GET /metrics

Returns Prometheus-compatible metrics.

Deprecated Endpoints

Legacy Balance Check

GET /v1/balance
Authorization: Bearer {api_key}

⚠️ Deprecated: Use /v1/wallet/balance instead.

Rate Limits

All endpoints are subject to rate limiting:

Endpoint Type	Limit	Window
AI Generation	100/min	1 minute
Wallet Operations	10/min	1 minute
Info/Discovery	60/min	1 minute

Rate limit information is included in response headers.

Next Steps

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

11 KiB Raw Blame History

API Endpoints

Chat Completions

Create Chat Completion

Streaming Response

Completions

Create Completion

Embeddings

Create Embeddings

Images

Create Image

Audio

Create Transcription

Create Translation

Models

List Models

Get Model

Wallet Management

Create API Key

Check Balance

Top Up Balance

Withdraw Balance

Node Information

Get Node Info

Discovery

List Providers

Admin Endpoints

Admin Dashboard

Admin API

Health & Status

Health Check

Metrics

Deprecated Endpoints

Legacy Balance Check

Rate Limits

Next Steps

11 KiB

Raw Blame History