zap-stream-core/API.md

zap.stream API Documentation

This document describes the REST API endpoints available in the zap.stream core streaming server.

Authentication

The API uses NIP-98 (Nostr HTTP Auth) for authentication. All protected endpoints require an Authorization header with the following format:

Authorization: Nostr <base64-encoded-nostr-event>

The Nostr event must:

• Be of kind 27235 (NIP-98 HTTP Auth)
• Have a valid signature
• Include appropriate method and url tags matching the request
• Have a recent timestamp (within acceptable time window)

Base URL

All API endpoints are prefixed with /api/v1/

Endpoints

Account Management

Get Account Information

GET /api/v1/account

Authentication: Required

Response:

{
  "endpoints": [
    {
      "name": "string",
      "url": "string", 
      "key": "string",
      "capabilities": ["string"],
      "cost": {
        "unit": "string",
        "rate": 0.0
      }
    }
  ],
  "balance": 0,
  "tos": {
    "accepted": false,
    "link": "string"
  },
  "forwards": [
    {
      "id": 0,
      "name": "string"
    }
  ],
  "details": {
    "title": "string",
    "summary": "string", 
    "image": "string",
    "tags": ["string"],
    "content_warning": "string",
    "goal": "string"
  }
}

Description: Returns comprehensive account information including streaming endpoints, account balance, terms of service status, forward destinations, and stream details.

Update Account

PATCH /api/v1/account

Authentication: Required

Request Body:

{
  "accept_tos": true
}

Response:

{}

Description: Updates account settings, primarily used for accepting terms of service.

Payment Operations

Request Top-up

GET /api/v1/topup?amount=<amount>

Authentication: Required

Query Parameters:

• amount (required): Amount to top up in millisatoshi

Response:

{
  "pr": "string"
}

Description: Generates a Lightning Network payment request for adding funds to the account balance. Returns a payment request (invoice) that can be paid to credit the account.

Withdraw Funds

POST /api/v1/withdraw?invoice=<payment_request>

Authentication: Required

Query Parameters:

• invoice (required): Lightning Network payment request to pay

Response:

{
  "fee": 0,
  "preimage": "string"
}

Description: Withdraws funds from the account balance by paying a Lightning Network invoice. Returns the fee charged and payment preimage on success.

Stream Management

Update Stream Event

PATCH /api/v1/event

Authentication: Required

Request Body:

{
  "id": "string",
  "title": "string",
  "summary": "string",
  "image": "string", 
  "tags": ["string"],
  "content_warning": "string",
  "goal": "string"
}

Response:

{}

Description: Updates stream event metadata such as title, description, image, tags, content warnings, and goals.

Forward Management

Create Forward

POST /api/v1/forward

Authentication: Required

Request Body:

{
  "name": "string",
  "target": "string"
}

Response:

{
  "id": 0
}

Description: Creates a new payment forward destination. Forwards allow automatic routing of payments to external Lightning addresses or Nostr zap targets.

Delete Forward

DELETE /api/v1/forward/{id}

Authentication: Required

Path Parameters:

• id: Forward ID to delete

Response:

{}

Description: Removes a payment forward destination by ID.

History and Keys

Get Account History

GET /api/v1/history

Authentication: Required

Response:

{
  "items": [
    {
      "created": 0,
      "type": 0,
      "amount": 0.0,
      "desc": "string"
    }
  ],
  "page": 0,
  "page_size": 0
}

Description: Returns paginated transaction history for the account including payments, withdrawals, and streaming costs.

Get Stream Keys

GET /api/v1/keys

Authentication: Required

Response:

[
  {
    "id": 0,
    "key": "string",
    "created": 0,
    "expires": 0,
    "stream_id": "string"
  }
]

Description: Returns all active stream keys for the account.

Create Stream Key

POST /api/v1/keys

Authentication: Required

Request Body:

{
  "event": {
    "title": "string",
    "summary": "string",
    "image": "string",
    "tags": ["string"], 
    "content_warning": "string",
    "goal": "string"
  },
  "expires": "2024-01-01T00:00:00Z"
}

Response:

{
  "key": "string",
  "event": "string"
}

Description: Creates a new stream key with associated event metadata and optional expiration time.

Error Handling

All endpoints return appropriate HTTP status codes:

• 200 OK - Successful request
• 400 Bad Request - Invalid request parameters or body
• 401 Unauthorized - Missing or invalid authentication
• 404 Not Found - Resource not found
• 500 Internal Server Error - Server error

Error responses include a JSON body with error details where applicable.

Rate Limiting

The API may implement rate limiting based on account balance and usage patterns. Specific limits are not documented but will be enforced server-side.

CORS Support

The API includes CORS headers allowing cross-origin requests from web applications:

Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: *
Access-Control-Allow-Methods: HEAD, GET, PATCH, DELETE, POST, OPTIONS

Content Type

All API endpoints expect and return application/json content type unless otherwise specified.