API Reference

The Syphon registry API. Base URL: https://syphon-api.vercel.app (env: NEXT_PUBLIC_API_URL)

Overview

All endpoints return JSON. Successful responses use HTTP 200/201. Errors use 4xx/5xx with a consistent error body. Paginated endpoints accept limit (max 100) and offset query params.

Authentication

Pass a bearer token in the Authorization header:

curl https://syphon-api.vercel.app/v1/users/me \
  -H "Authorization: Bearer syph_xxxxxxxx..."

Tokens start with syph_. Create them with syphon token create. Supabase JWTs (from web login) are also accepted.

Error shape

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Package not found: github-tools",
    "retry_after": null
  }
}

Status	Meaning
400	Bad request — validation error
401	Missing or invalid auth token
403	Forbidden — valid token but insufficient permissions
404	Resource not found
409	Conflict — e.g. version already published
422	Unprocessable — e.g. failed signature verification
429	Rate limit exceeded — see Retry-After header
500	Internal server error

Auth routes

POST/v1/auth/devicedevice-poll rate

Start a device-code OAuth flow. Returns a user_code to display to the user and a device_code for polling.

Response

{ "device_code": "...", "user_code": "ABCD-1234", "verification_uri": "https://syphon-web.vercel.app/activate", "expires_in": 900, "interval": 5 }

POST/v1/auth/device/poll

Poll for device-code flow completion. Call every interval seconds until you get a token or an error.

Request body

{ "device_code": "..." }

Response

{ "token": "syph_...", "user": { "username": "...", "email": "..." } }

POST/v1/auth/activateauth required

Approve a pending device-code request. Called by the web UI when the user clicks 'Approve'. Requires auth (token:write scope).

Request body

{ "user_code": "ABCD-1234" }

POST/v1/auth/signup

Create a new account.

Request body

{ "email": "...", "password": "...", "username": "..." }

Response

{ "user": { "id": "...", "username": "..." } }

POST/v1/auth/signin

Request body

{ "email": "...", "password": "..." }

Response

{ "token": "syph_...", "user": { "username": "..." } }

Package routes

GET/v1/packages

Search the registry. Query params: search, category, verified, sort, limit (max 100), offset.

Response

{ "packages": [...], "total": 42 }

POST/v1/packagesauth requiredpublish rate

Publish a new version. Multipart/form-data: tarball (file), meta (JSON string). Meta includes manifest, signature (base64), checksum (SHA-256), pubkey (hex), tag, access.

Response

{ "name": "github-tools", "version": "1.0.0", "created_at": "..." }

GET/v1/packages/:name

Get full package details: metadata, all versions, download count, star count, author info.

Response

{ "id": "...", "name": "...", "description": "...", "latest_version": "1.0.0", "downloads": 2400, "stars": 12, "author": { "username": "...", "pubkey": "..." }, "versions": [...] }

DELETE/v1/packages/:nameauth required

Delete the entire package (all versions). Only available within 72 hours of first publish, or to org owners.

GET/v1/packages/:name/readme

Get the package README as plain text. Cached — updates after each publish.

Response

{ "content": "# github-tools
..." }

GET/v1/packages/:name/downloads

Get download counts by day for the last 30 days.

Response

{ "total": 2400, "daily": [{ "date": "2026-05-01", "count": 80 }, ...] }

POST/v1/packages/:name/starauth required

Toggle a star on a package.

Response

{ "starred": true }

POST/v1/packages/:name/transferauth required

Transfer package ownership to another user or org.

Request body

{ "to": "new-owner" }

PUT/v1/packages/:name/accessauth required

Change package visibility.

Request body

{ "access": "public" | "private" }

POST/v1/packages/:name/deprecateauth required

Mark a package as deprecated with an optional message.

Request body

{ "message": "Use my-new-package instead" }

Version routes

GET/v1/packages/:name/versions/:version

Get version metadata and a signed download URL for the tarball.

Response

{ "version": "1.0.0", "tarball_url": "https://...", "checksum_sha256": "...", "signature_ed25519": "...", "author_pubkey": "...", "published_at": "..." }

DELETE/v1/packages/:name/versions/:versionauth required

Unpublish a specific version. Only within 72 hours of publish.

GET/v1/packages/:name/files

List files in the latest version tarball.

Response

{ "files": [{ "name": "dist/index.js", "size": 24300 }, ...] }

User routes

GET/v1/users/meauth required

Get the authenticated user's profile, package count, total downloads, and org memberships.

Response

{ "user": { "username": "...", "email": "...", "display_name": "...", "created_at": "..." }, "package_count": 7, "total_downloads": 12400, "orgs": ["my-org"] }

PATCH/v1/users/meauth required

Update profile fields. All fields optional.

Request body

{ "display_name": "Misbah", "bio": "...", "website": "https://...", "github_url": "https://github.com/...", "avatar_url": "https://...", "location": "London", "twitter": "@handle" }

PUT/v1/users/me/pubkeyauth required

Request body

{ "pubkey": "a3f8b2c1..." }

GET/v1/users/:username

Get a user's public profile and package list.

Response

{ "username": "...", "packages": [...], "total_downloads": 12400 }

Org routes

POST/v1/orgsauth required

Create a new organisation.

Request body

{ "name": "my-org" }

GET/v1/orgs/:orgauth required

Get org details and member list.

POST/v1/orgs/:org/invitesauth required

Invite a user to the org.

Request body

{ "username": "alice", "role": "member" | "admin" }

DELETE/v1/orgs/:org/members/:usernameauth required

Remove a member from the org.

Token routes

POST/v1/tokensauth required

Create a new API token. Named tokens default to read-only; request scopes explicitly. The plain-text token is only returned once.

Request body

{ "name": "ci-deploy", "expires_in_days": 90, "scopes": ["publish"] }

Response

{ "id": "...", "plaintext": "syph_...", "name": "ci-deploy", "scopes": ["publish"], "expires_at": "..." }

GET/v1/tokensauth required

List all tokens (without the plain-text value).

Response

{ "tokens": [{ "id": "...", "name": "ci-deploy", "prefix": "syph_ab", "scopes": ["publish"], "created_at": "...", "expires_at": "...", "last_used_at": "..." }] }

DELETE/v1/tokens/:idauth required

Revoke a token immediately.

Installed (sync)

Sync API — persists your per-machine install state to the cloud so syphon sync can restore it on a new machine.

GET/v1/installedauth required

Get all installed packages for the authenticated user. Query param: profile (optional label).

Response

{ "installed": [{ "name": "github-tools", "version": "1.0.0", "checksum_sha256": "...", "linked_frameworks": ["claude-code"], "profile": null }] }

PUT/v1/installed/:nameauth required

Upsert one installed package record.

Request body

{ "version": "1.0.0", "checksum_sha256": "...", "signature_ed25519": "...", "author_pubkey": "...", "linked_frameworks": ["claude-code"], "profile": null }

Response

{ "ok": true, "id": "..." }

DELETE/v1/installed/:nameauth required

Remove an installed package record. Query param: profile.

POST/v1/installed/bulk-replaceauth requiredstrict rate

Replace the entire install list for the authenticated user + profile in one atomic operation.

Request body

{ "packages": [...], "profile": null }

Response

{ "replaced": 7 }

Advisory routes

GET/v1/advisories

List all active advisories. Query params: package, severity (low|medium|high|critical).

Response

{ "advisories": [{ "id": "...", "package": "...", "affected_versions": "^1.0.0", "severity": "high", "description": "...", "published_at": "..." }] }

POST/v1/advisories/check

Check a list of packages against the advisory database. Returns only the packages with known vulnerabilities.

Request body

{ "packages": [{ "name": "github-tools", "version": "1.0.0" }] }

Response

{ "advisories": [{ "id": "...", "package": "github-tools", "vulnerable_versions": "^1.0.0", "patched_versions": ">=1.1.0", "severity": "high", "summary": "...", "url": "...", "published_at": "..." }] }

Webhook routes

GET/v1/webhooksauth required

List webhooks for the authenticated user.

Response

{ "webhooks": [{ "id": "...", "url": "https://...", "events": ["package.published"], "created_at": "..." }] }

POST/v1/webhooksauth required

Create a webhook. Supported events: package.published, package.yanked, package.deprecated.

Request body

{ "url": "https://your-server.example.com/hook", "events": ["package.published", "package.yanked"] }

Response

{ "id": "...", "url": "...", "events": [...], "created_at": "..." }

Stats routes

GET/v1/packages/trending

Get trending packages (most downloaded in the last 7 days). Query param: limit (max 50).

Response

{ "packages": [...] }

GET/v1/packages/categories

Get all categories with package counts.

Response

{ "categories": [{ "name": "devtools", "count": 42 }] }

GET/v1/packages/tags

Get all tags. Query param: search.

Misc routes

GET/v1/health

Registry health check. Returns 200 if the API is up.

Response

{ "status": "ok", "timestamp": "..." }

Loading…

API Reference

The Syphon registry API. Base URL: https://syphon-api.vercel.app (env: NEXT_PUBLIC_API_URL)

Overview

All endpoints return JSON. Successful responses use HTTP 200/201. Errors use 4xx/5xx with a consistent error body. Paginated endpoints accept limit (max 100) and offset query params.

Authentication

Pass a bearer token in the Authorization header:

curl https://syphon-api.vercel.app/v1/users/me \
  -H "Authorization: Bearer syph_xxxxxxxx..."

Tokens start with syph_. Create them with syphon token create. Supabase JWTs (from web login) are also accepted.

Error shape

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Package not found: github-tools",
    "retry_after": null
  }
}

Status	Meaning
400	Bad request — validation error
401	Missing or invalid auth token
403	Forbidden — valid token but insufficient permissions
404	Resource not found
409	Conflict — e.g. version already published
422	Unprocessable — e.g. failed signature verification
429	Rate limit exceeded — see Retry-After header
500	Internal server error

Auth routes

POST/v1/auth/devicedevice-poll rate

Start a device-code OAuth flow. Returns a user_code to display to the user and a device_code for polling.

Response

{ "device_code": "...", "user_code": "ABCD-1234", "verification_uri": "https://syphon-web.vercel.app/activate", "expires_in": 900, "interval": 5 }

POST/v1/auth/device/poll

Poll for device-code flow completion. Call every interval seconds until you get a token or an error.

Request body

{ "device_code": "..." }

Response

{ "token": "syph_...", "user": { "username": "...", "email": "..." } }

POST/v1/auth/activateauth required

Approve a pending device-code request. Called by the web UI when the user clicks 'Approve'. Requires auth (token:write scope).

Request body

{ "user_code": "ABCD-1234" }

POST/v1/auth/signup

Create a new account.

Request body

{ "email": "...", "password": "...", "username": "..." }

Response

{ "user": { "id": "...", "username": "..." } }

POST/v1/auth/signin

Request body

{ "email": "...", "password": "..." }

Response

{ "token": "syph_...", "user": { "username": "..." } }

Package routes

GET/v1/packages

Search the registry. Query params: search, category, verified, sort, limit (max 100), offset.

Response

{ "packages": [...], "total": 42 }

POST/v1/packagesauth requiredpublish rate

Publish a new version. Multipart/form-data: tarball (file), meta (JSON string). Meta includes manifest, signature (base64), checksum (SHA-256), pubkey (hex), tag, access.

Response

{ "name": "github-tools", "version": "1.0.0", "created_at": "..." }

GET/v1/packages/:name

Get full package details: metadata, all versions, download count, star count, author info.

Response

{ "id": "...", "name": "...", "description": "...", "latest_version": "1.0.0", "downloads": 2400, "stars": 12, "author": { "username": "...", "pubkey": "..." }, "versions": [...] }

DELETE/v1/packages/:nameauth required

Delete the entire package (all versions). Only available within 72 hours of first publish, or to org owners.

GET/v1/packages/:name/readme

Get the package README as plain text. Cached — updates after each publish.

Response

{ "content": "# github-tools
..." }

GET/v1/packages/:name/downloads

Get download counts by day for the last 30 days.

Response

{ "total": 2400, "daily": [{ "date": "2026-05-01", "count": 80 }, ...] }

POST/v1/packages/:name/starauth required

Toggle a star on a package.

Response

{ "starred": true }

POST/v1/packages/:name/transferauth required

Transfer package ownership to another user or org.

Request body

{ "to": "new-owner" }

PUT/v1/packages/:name/accessauth required

Change package visibility.

Request body

{ "access": "public" | "private" }

POST/v1/packages/:name/deprecateauth required

Mark a package as deprecated with an optional message.

Request body

{ "message": "Use my-new-package instead" }

Version routes

GET/v1/packages/:name/versions/:version

Get version metadata and a signed download URL for the tarball.

Response

{ "version": "1.0.0", "tarball_url": "https://...", "checksum_sha256": "...", "signature_ed25519": "...", "author_pubkey": "...", "published_at": "..." }

DELETE/v1/packages/:name/versions/:versionauth required

Unpublish a specific version. Only within 72 hours of publish.

GET/v1/packages/:name/files

List files in the latest version tarball.

Response

{ "files": [{ "name": "dist/index.js", "size": 24300 }, ...] }

User routes

GET/v1/users/meauth required

Get the authenticated user's profile, package count, total downloads, and org memberships.

Response

{ "user": { "username": "...", "email": "...", "display_name": "...", "created_at": "..." }, "package_count": 7, "total_downloads": 12400, "orgs": ["my-org"] }

PATCH/v1/users/meauth required

Update profile fields. All fields optional.

Request body

{ "display_name": "Misbah", "bio": "...", "website": "https://...", "github_url": "https://github.com/...", "avatar_url": "https://...", "location": "London", "twitter": "@handle" }

PUT/v1/users/me/pubkeyauth required

Request body

{ "pubkey": "a3f8b2c1..." }

GET/v1/users/:username

Get a user's public profile and package list.

Response

{ "username": "...", "packages": [...], "total_downloads": 12400 }

Org routes

POST/v1/orgsauth required

Create a new organisation.

Request body

{ "name": "my-org" }

GET/v1/orgs/:orgauth required

Get org details and member list.

POST/v1/orgs/:org/invitesauth required

Invite a user to the org.

Request body

{ "username": "alice", "role": "member" | "admin" }

DELETE/v1/orgs/:org/members/:usernameauth required

Remove a member from the org.

Token routes

POST/v1/tokensauth required

Create a new API token. Named tokens default to read-only; request scopes explicitly. The plain-text token is only returned once.

Request body

{ "name": "ci-deploy", "expires_in_days": 90, "scopes": ["publish"] }

Response

{ "id": "...", "plaintext": "syph_...", "name": "ci-deploy", "scopes": ["publish"], "expires_at": "..." }

GET/v1/tokensauth required

List all tokens (without the plain-text value).

Response

{ "tokens": [{ "id": "...", "name": "ci-deploy", "prefix": "syph_ab", "scopes": ["publish"], "created_at": "...", "expires_at": "...", "last_used_at": "..." }] }

DELETE/v1/tokens/:idauth required

Revoke a token immediately.

Installed (sync)

Sync API — persists your per-machine install state to the cloud so syphon sync can restore it on a new machine.

GET/v1/installedauth required

Get all installed packages for the authenticated user. Query param: profile (optional label).

Response

{ "installed": [{ "name": "github-tools", "version": "1.0.0", "checksum_sha256": "...", "linked_frameworks": ["claude-code"], "profile": null }] }

PUT/v1/installed/:nameauth required

Upsert one installed package record.

Request body

{ "version": "1.0.0", "checksum_sha256": "...", "signature_ed25519": "...", "author_pubkey": "...", "linked_frameworks": ["claude-code"], "profile": null }

Response

{ "ok": true, "id": "..." }

DELETE/v1/installed/:nameauth required

Remove an installed package record. Query param: profile.

POST/v1/installed/bulk-replaceauth requiredstrict rate

Replace the entire install list for the authenticated user + profile in one atomic operation.

Request body

{ "packages": [...], "profile": null }

Response

{ "replaced": 7 }

Advisory routes

GET/v1/advisories

List all active advisories. Query params: package, severity (low|medium|high|critical).

Response

{ "advisories": [{ "id": "...", "package": "...", "affected_versions": "^1.0.0", "severity": "high", "description": "...", "published_at": "..." }] }

POST/v1/advisories/check

Check a list of packages against the advisory database. Returns only the packages with known vulnerabilities.

Request body

{ "packages": [{ "name": "github-tools", "version": "1.0.0" }] }

Response

{ "advisories": [{ "id": "...", "package": "github-tools", "vulnerable_versions": "^1.0.0", "patched_versions": ">=1.1.0", "severity": "high", "summary": "...", "url": "...", "published_at": "..." }] }

Webhook routes

GET/v1/webhooksauth required

List webhooks for the authenticated user.

Response

{ "webhooks": [{ "id": "...", "url": "https://...", "events": ["package.published"], "created_at": "..." }] }

POST/v1/webhooksauth required

Create a webhook. Supported events: package.published, package.yanked, package.deprecated.

Request body

{ "url": "https://your-server.example.com/hook", "events": ["package.published", "package.yanked"] }

Response

{ "id": "...", "url": "...", "events": [...], "created_at": "..." }

Stats routes

GET/v1/packages/trending

Get trending packages (most downloaded in the last 7 days). Query param: limit (max 50).

Response

{ "packages": [...] }

GET/v1/packages/categories

Get all categories with package counts.

Response

{ "categories": [{ "name": "devtools", "count": 42 }] }

GET/v1/packages/tags

Get all tags. Query param: search.

Misc routes

GET/v1/health

Registry health check. Returns 200 if the API is up.

Response

{ "status": "ok", "timestamp": "..." }