API Reference

Create a new account. Returns your first API key and your managed Nostr pubkey. A verification email is sent automatically.

Request body

Response

{
  "user_id": "uuid",
  "api_key": "nk_live_...",
  "api_key_id": "uuid",
  "pubkey": "hex pubkey",
  "npub": "npub1...",
  "message": "Account created. Check your email to verify."
}

Create an additional API key. Free tier allows 2 keys, Pro allows 10.

Request body

Response

{
  "api_key": "nk_live_...",
  "api_key_id": "uuid",
  "pubkey": "hex pubkey"
}

Returns all active API keys for your account.

Response

{
  "keys": [
    {
      "id": "uuid",
      "name": "default",
      "tier": "free",
      "keypair_mode": "managed",
      "managed_pubkey": "hex pubkey",
      "is_active": true,
      "last_used_at": 1712345678,
      "created_at": 1712300000
    }
  ]
}

Permanently revokes an API key. You cannot revoke your last active key.

Response

{ "ok": true }

Invalidates the current key secret and issues a new one with the same ID and settings.

Response

{
  "api_key": "nk_live_...",
  "api_key_id": "uuid"
}

Returns the managed Nostr public key associated with this API key.

Response

{
  "pubkey": "abc123...",
  "npub": "npub1..."
}

Publishes a kind-1 text note (the most common Nostr event type).

Request body

Example

curl -X POST https://gateway.agilesolutionlabs.com/v1/posts \
  -H "Authorization: Bearer nk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Hello from Nostr Gateway!",
    "tags": [["t", "nostr"], ["t", "bitcoin"]]
  }'

Response

{
  "event_id": "hex event id",
  "pubkey": "hex pubkey",
  "relay_results": [
    { "relay": "wss://relay.example.com", "ok": true }
  ]
}

Publishes a kind-0 metadata event (profile update).

Request body

Example

curl -X POST https://gateway.agilesolutionlabs.com/v1/profiles \
  -H "Authorization: Bearer nk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alice",
    "about": "Building on Nostr",
    "picture": "https://example.com/avatar.png"
  }'

Publishes a kind-7 reaction (like/dislike) to another event.

Request body

Publishes a kind-6 repost of another event.

Request body

Publishes a kind-4 encrypted direct message (NIP-04).

Request body

Publishes a kind-3 contact list (follow list). Replaces the existing follow list.

Request body

Example

{
  "follows": [
    "abc123...",
    "def456..."
  ]
}

Publish any Nostr event kind. The event is signed automatically with your managed keypair (or your BYOK key).

Request body

Example — publish a long-form article (kind 30023)

{
  "kind": 30023,
  "content": "# My Article\n\nLong form content here...",
  "tags": [
    ["title", "My Article"],
    ["d", "my-article-slug"]
  ]
}

Query events from the relay using NIP-01 filter parameters.

Query parameters

Example

curl "https://gateway.agilesolutionlabs.com/v1/events?kinds=1&limit=10" \
  -H "Authorization: Bearer nk_live_..."

Response

{
  "events": [
    {
      "id": "hex event id",
      "pubkey": "hex pubkey",
      "kind": 1,
      "content": "Hello Nostr!",
      "created_at": 1712345678,
      "tags": [],
      "sig": "hex signature"
    }
  ]
}

Fetch a single event by its hex ID.

Example

curl https://gateway.agilesolutionlabs.com/v1/events/abc123... \
  -H "Authorization: Bearer nk_live_..."

Fetch a Nostr profile (kind-0 metadata) by hex pubkey.

Response

{
  "pubkey": "hex pubkey",
  "name": "Alice",
  "about": "Building on Nostr",
  "picture": "https://...",
  "nip05": "alice@example.com"
}

Returns request counts and per-endpoint breakdown for the current API key.

Query parameters

Response

{
  "period": "today",
  "total_requests": 142,
  "successful_requests": 138,
  "failed_requests": 4,
  "by_endpoint": [
    { "endpoint": "/v1/posts", "cnt": 80 },
    { "endpoint": "/v1/events", "cnt": 62 }
  ],
  "rate_limit": {
    "rpm_limit": 10,
    "rpd_limit": 1000
  }
}