🌐

REST API

Integrate elephant.md into any platform with the REST API.

Get Started

1
Get a token
Log in via the CLI (npx elephant-md login github) or OAuth, then grab your token from ~/.tusk/config.json.

Make a request

curl https://elephant.md/api/v1/health
# => { "status": "ok" }

Authenticate

curl -H "Authorization: Bearer <token>" \
  https://elephant.md/api/v1/documents

Authentication

Pass a Bearer token in the Authorization header, or set the elephant_token cookie. Public endpoints work without authentication.

Header

Authorization: Bearer <your-token>

Documents

POST/api/v1/documentsAuth

Create a new document.

Request body

{
  "title": "My Document",
  "content": "# Hello world",
  "category": "guide",
  "visibility": "public",
  "slug": "my-document",
  "description": "A short description",
  "tags": ["ai", "agents"]
}

Param	Type	Note
title	string	required
content	string	required — markdown
category	string	required — guide, reference, tutorial, blog, note, snippet, doc
visibility	string	public, unlisted (default), private
slug	string	Auto-generated from title if omitted
tags	string[]	Optional tag list

GET/api/v1/documentsAuth

List your documents. Supports filtering and pagination.

Query	Type	Note
visibility	string	Filter by visibility
category	string	Filter by category
limit	number	1–100, default 20
offset	number	Pagination offset

GET/api/v1/documents/@:user/:slug

Fetch a document's full content and metadata.

POST/api/v1/documents/:id/versionsAuth

Push a new version of an existing document.

Request body

{ "content": "# Updated content" }

PATCH/api/v1/documents/:idAuth

Update document metadata (title, visibility, tags, etc.).

Request body

{
  "title": "New Title",
  "visibility": "public",
  "category": "guide",
  "tags": ["updated"],
  "pin_order": 1
}

DELETE/api/v1/documents/:idAuth

Permanently delete a document and all its versions.

POST/api/v1/documents/:id/restoreAuth

Restore a previous version by content hash.

Request body

{ "hash": "abc123..." }

Burn Links

Create self-destructing documents by adding burn fields to the create endpoint. Two modes: timed (expires at a timestamp) and viewonce (destroyed after first view).

POST/api/v1/documentsAuth

Create a burn link.

Request body

{
  "title": "Secret credentials",
  "content": "...",
  "category": "note",
  "isBurn": true,
  "burnMode": "viewonce",
  "burnExpiresAt": "2025-12-31T00:00:00Z"
}

Param	Type	Note
isBurn	boolean	required — set to true
burnMode	string	timed (default) or viewonce
burnExpiresAt	ISO 8601	required — expiration timestamp

Search & Discovery

GET/api/v1/search

Hybrid full-text and semantic search across public documents.

Query	Type	Note
q	string	required — search query
category	string	Filter by category
tag	string	Filter by tag
limit	number	1–100, default 20

Response

{
  "results": [...],
  "total": 42,
  "query": "react hooks",
  "mode": "semantic"
}

GET/api/v1/trending

Get trending documents, optionally filtered by category.

Query	Type	Note
category	string	Filter by category
limit	number	1–50, default 20

Bookmarks

POST/api/v1/documents/:id/bookmarkAuth

Toggle a bookmark on a document. Calling again removes it.

Response

{
  "bookmarked": true,
  "bookmarkCount": 12
}

GET/api/v1/bookmarksAuth

List your bookmarked documents with pagination.

Query	Type	Note
limit	number	1–100, default 20
offset	number	Pagination offset

Collections

Organize documents into named collections. All endpoints require authentication.

POST/api/v1/collectionsAuth

Create a new collection.

Request body

{
  "name": "AI Agents Toolkit",
  "description": "Essential prompts and configs",
  "visibility": "public"
}

GET/api/v1/collectionsAuth

List your collections with item counts.

GET/api/v1/collections/:id

Get a collection's details and all its items.

PATCH/api/v1/collections/:idAuth

Update collection name, description, or visibility.

Request body

{
  "name": "Updated Name",
  "visibility": "private"
}

DELETE/api/v1/collections/:idAuth

Delete a collection. Items are not deleted.

POST/api/v1/collections/:id/itemsAuth

Add a document to a collection.

Request body

{ "documentId": "abc-123-..." }

DELETE/api/v1/collections/:id/items/:docIdAuth

Remove a document from a collection.

PATCH/api/v1/collections/:id/itemsAuth

Reorder items in a collection.

Request body

{ "order": ["id-1", "id-2", "id-3"] }

Users & Profiles

GET/api/v1/users/@:username

Get a public user profile with their documents.

Query	Type	Note
limit	number	1–100, default 20
offset	number	Pagination offset

Response

{
  "username": "nickbrooks",
  "displayName": "Nick Brooks",
  "bio": "...",
  "avatarUrl": "https://...",
  "documents": [...],
  "total": 15
}

Installs

Track agent installs for documents. Used by the CLI and MCP server to record which documents have been installed.

POST/api/v1/installsAuth

Record a document install.

Request body

{
  "documentId": "abc-123-...",
  "agentType": "claude"
}

GET/api/v1/installsAuth

List your installed documents.

Rate Limits

Rates scale with your trust tier (0–3). Every response includes rate limit headers.

Response headers

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1709836800

When rate limited, the API returns 429 with a retryAfter field in seconds.

Error Handling

All errors return a consistent JSON shape with an error code and human-readable message.

Error response

{
  "ok": false,
  "code": "NOT_FOUND",
  "message": "Document not found"
}

Code	Status	Meaning
UNAUTHORIZED	401	Missing or invalid token
NOT_FOUND	404	Resource does not exist
VALIDATION_ERROR	400	Invalid request data
CONFLICT	409	Slug or resource already exists
RATE_LIMITED	429	Too many requests
CONTENT_BLOCKED	422	Content scanning rejected