API Reference | Benlon

Quick Start

Get started with the Benlon API in minutes. All requests are made to our REST API endpoint.

https://api.benlon.com/v1

# Install the API client (example with curl)
curl https://api.benlon.com/v1/projects \
  -H "Authorization: Bearer YOUR_API_KEY"

Authentication

All API requests must be authenticated using a Bearer token. Generate API keys from your account settings under Settings → API Keys.

curl https://api.benlon.com/v1/projects \
  -H "Authorization: Bearer dt_live_abc123xyz789"

Security: Keep your API keys secret. Never commit them to version control or expose them in client-side code. Rotate keys regularly.

Projects

Projects represent connected repositories and their documentation. Manage projects, trigger syncs, and access generated documentation.

GET/projects

Retrieve a paginated list of all projects in your workspace.

Parameters

pageintegerPage number (default: 1)

limitintegerItems per page (default: 20, max: 100)

statusstringFilter by status: active, syncing, error

Example Request

curl https://api.benlon.com/v1/projects?page=1&limit=20 \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "data": [
    {
      "id": "proj_abc123",
      "name": "My API Project",
      "repository_url": "https://github.com/user/repo",
      "branch": "main",
      "status": "active",
      "last_synced": "2025-08-15T10:30:00Z",
      "created_at": "2025-08-01T09:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 5,
    "pages": 1
  }
}

GET/projects/:id

Get detailed information about a specific project, including sync status, configuration, and statistics.

Example Request

curl https://api.benlon.com/v1/projects/proj_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "id": "proj_abc123",
  "name": "My API Project",
  "repository_url": "https://github.com/user/repo",
  "branch": "main",
  "status": "active",
  "config": {
    "languages": ["typescript", "javascript"],
    "auto_sync": true,
    "sync_triggers": ["push", "merge"]
  },
  "stats": {
    "total_files": 1247,
    "documented_endpoints": 45,
    "last_analysis": "2025-08-15T10:30:00Z"
  },
  "last_synced": "2025-08-15T10:30:00Z",
  "created_at": "2025-08-01T09:00:00Z"
}

POST/projects

Create a new project and connect a repository. This will trigger an initial analysis.

Parameters

namestringProject name (required)

repository_urlstringFull repository URL (required)

branchstringDefault branch (default: main)

providerstringgithub, gitlab, or bitbucket (auto-detected)

Example Request

curl -X POST https://api.benlon.com/v1/projects \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My API Project",
    "repository_url": "https://github.com/user/repo",
    "branch": "main",
    "config": {
      "languages": ["typescript"],
      "auto_sync": true
    }
  }'

Example Response

{
  "id": "proj_abc123",
  "name": "My API Project",
  "status": "analyzing",
  "analysis_progress": 0,
  "created_at": "2025-08-15T10:30:00Z"
}

PATCH/projects/:id

Update project settings, configuration, or metadata.

Parameters

namestringProject name

branchstringDefault branch

configobjectConfiguration object

Example Request

curl -X PATCH https://api.benlon.com/v1/projects/proj_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Project Name",
    "config": {
      "auto_sync": false
    }
  }'

Example Response

{
  "id": "proj_abc123",
  "name": "Updated Project Name",
  "config": {
    "auto_sync": false
  },
  "updated_at": "2025-08-15T11:00:00Z"
}

DELETE/projects/:id

Delete a project and all associated documentation. This action cannot be undone.

Example Request

curl -X DELETE https://api.benlon.com/v1/projects/proj_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "deleted": true,
  "id": "proj_abc123"
}

Documentation

Access and manage generated documentation for your projects.

GET/projects/:id/docs

Retrieve all generated documentation for a project. Returns a structured tree of documentation pages.

Parameters

formatstringResponse format: json, markdown, html (default: json)

versionstringSpecific git commit or tag (default: latest)

Example Request

curl https://api.benlon.com/v1/projects/proj_abc123/docs \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "project_id": "proj_abc123",
  "version": "main@abc123",
  "pages": [
    {
      "id": "doc_api_ref",
      "title": "API Reference",
      "type": "api_reference",
      "path": "/api-reference",
      "updated_at": "2025-08-15T10:30:00Z"
    },
    {
      "id": "doc_getting_started",
      "title": "Getting Started",
      "type": "guide",
      "path": "/getting-started",
      "updated_at": "2025-08-15T10:30:00Z"
    }
  ]
}

GET/projects/:id/docs/:doc_id

Get the full content of a specific documentation page.

Parameters

formatstringResponse format: json, markdown, html

Example Request

curl https://api.benlon.com/v1/projects/proj_abc123/docs/doc_api_ref \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "id": "doc_api_ref",
  "title": "API Reference",
  "content": "# API Reference\n\n## Endpoints\n...",
  "format": "markdown",
  "metadata": {
    "endpoints_documented": 45,
    "last_synced": "2025-08-15T10:30:00Z"
  }
}

POST/projects/:id/sync

Manually trigger a documentation sync. This will re-analyze the repository and update all documentation.

Parameters

forcebooleanForce sync even if no changes detected (default: false)

Example Request

curl -X POST https://api.benlon.com/v1/projects/proj_abc123/sync \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "force": false
  }'

Example Response

{
  "sync_id": "sync_xyz789",
  "status": "queued",
  "estimated_duration": 300,
  "started_at": "2025-08-15T10:30:00Z"
}

GET/projects/:id/sync/:sync_id

Get the status of a documentation sync operation.

Example Request

curl https://api.benlon.com/v1/projects/proj_abc123/sync/sync_xyz789 \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "sync_id": "sync_xyz789",
  "status": "completed",
  "progress": 100,
  "started_at": "2025-08-15T10:30:00Z",
  "completed_at": "2025-08-15T10:35:00Z",
  "results": {
    "files_analyzed": 1247,
    "docs_updated": 12,
    "docs_created": 3,
    "errors": []
  }
}

Search & Query

Search documentation and query your codebase using natural language.

POST/projects/:id/query

Query your codebase using natural language. Returns relevant code snippets, documentation, and explanations.

Parameters

querystringNatural language question (required)

contextstringAdditional context to narrow results

max_resultsintegerMaximum number of results (default: 5)

Example Request

curl -X POST https://api.benlon.com/v1/projects/proj_abc123/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "How do I authenticate API requests?",
    "max_results": 5
  }'

Example Response

{
  "query": "How do I authenticate API requests?",
  "results": [
    {
      "type": "code",
      "file": "src/auth/middleware.ts",
      "snippet": "export const authenticate = async (req, res, next) => {...}",
      "relevance": 0.95
    },
    {
      "type": "documentation",
      "title": "Authentication Guide",
      "path": "/guides/authentication",
      "relevance": 0.88
    }
  ],
  "answer": "API requests are authenticated using Bearer tokens..."
}

GET/projects/:id/search

Search documentation and code using keywords.

Parameters

qstringSearch query (required)

typestringFilter: docs, code, all (default: all)

limitintegerResults limit (default: 20)

Example Request

curl "https://api.benlon.com/v1/projects/proj_abc123/search?q=authentication&type=docs" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "query": "authentication",
  "results": [
    {
      "type": "documentation",
      "title": "Authentication Guide",
      "path": "/guides/authentication",
      "snippet": "Learn how to authenticate API requests...",
      "score": 0.92
    }
  ],
  "total": 1
}

Webhooks

Configure webhooks to receive real-time notifications about documentation updates, sync events, and project changes.

GET/webhooks

List all webhooks configured for your workspace.

Example Request

curl https://api.benlon.com/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "data": [
    {
      "id": "wh_abc123",
      "url": "https://your-app.com/webhooks/benlon",
      "events": ["docs.synced", "docs.changed"],
      "active": true,
      "created_at": "2025-08-01T09:00:00Z"
    }
  ]
}

POST/webhooks

Create a new webhook endpoint.

Parameters

urlstringWebhook URL (required)

eventsarrayArray of event types to subscribe to (required)

secretstringSecret for signature verification

Example Request

curl -X POST https://api.benlon.com/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/benlon",
    "events": ["docs.synced", "docs.changed", "project.updated"],
    "secret": "your-webhook-secret"
  }'

Example Response

{
  "id": "wh_abc123",
  "url": "https://your-app.com/webhooks/benlon",
  "events": ["docs.synced", "docs.changed", "project.updated"],
  "active": true,
  "created_at": "2025-08-15T10:30:00Z"
}

Available Events

project.created

A new project is created

project.updated

Project settings are updated

project.deleted

A project is deleted

docs.synced

Documentation sync is completed

docs.changed

Documentation content has changed

sync.started

A sync operation has started

sync.failed

A sync operation has failed

error.occurred

An error occurred in the project

Webhook Payload

All webhook payloads include a signature header for verification:

{
  "event": "docs.synced",
  "timestamp": "2025-08-15T10:30:00Z",
  "project_id": "proj_abc123",
  "data": {
    "sync_id": "sync_xyz789",
    "changes": 15,
    "files_updated": 8,
    "duration_seconds": 300
  }
}

// Headers:
// X-Benlon-Signature: sha256=abc123...
// X-Benlon-Event: docs.synced
// X-Benlon-Timestamp: 2025-08-15T10:30:00Z

Workspaces

Manage workspaces, team members, and permissions.

GET/workspaces

List all workspaces you have access to.

Example Request

curl https://api.benlon.com/v1/workspaces \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "data": [
    {
      "id": "ws_abc123",
      "name": "My Workspace",
      "plan": "pro",
      "member_count": 12,
      "created_at": "2025-08-01T09:00:00Z"
    }
  ]
}

GET/workspaces/:id/members

List all members of a workspace.

Example Request

curl https://api.benlon.com/v1/workspaces/ws_abc123/members \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "data": [
    {
      "id": "user_xyz789",
      "email": "user@example.com",
      "role": "admin",
      "joined_at": "2025-08-01T09:00:00Z"
    }
  ]
}

Rate Limiting

API requests are rate limited to ensure service quality. Limits vary by plan:

Starter:100 requests per hour
Pro:1,000 requests per hour
Enterprise:Custom limits (contact sales)

Rate limit information is included in response headers:

X-RateLimit-Limit - Total requests allowed per window
X-RateLimit-Remaining - Requests remaining in current window
X-RateLimit-Reset - Unix timestamp when the limit resets

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 987
X-RateLimit-Reset: 1726401600

Error Handling

The API uses standard HTTP status codes. All errors return a JSON response with details:

200

Success

Request completed successfully

201

Created

Resource created successfully

400

Bad Request

Invalid request parameters

401

Unauthorized

Invalid or missing API key

403

Forbidden

Insufficient permissions

404

Not Found

Resource not found

429

Too Many Requests

Rate limit exceeded

500

Internal Server Error

Server error - contact support

Error responses include a structured error object:

{
  "error": {
    "code": "invalid_request",
    "message": "The repository URL is invalid",
    "details": {
      "field": "repository_url",
      "reason": "Must be a valid GitHub, GitLab, or Bitbucket URL"
    }
  }
}

SDKs & Libraries

Official SDKs are coming soon. In the meantime, use our REST API directly or build your own client.

JavaScript/TypeScript

Coming Q1 2026

npm install @benlon/sdk

Python

Coming Q1 2026

pip install benlon

Go

Coming Q2 2026

go get benlon.com/api

Security

• TLS 1.3 encryption
• OAuth 2.0 support
• API key rotation
• IP allowlisting (Enterprise)

Performance

• 99.9% uptime SLA (Enterprise)
• Global CDN
• < 200ms average response time
• WebSocket support (coming soon)

Need Help?

Have questions about the API? Our support team is here to help.

Contact Support View FAQ