API Reference | Docora Documentation

Docora exposes a REST API for repository management. All endpoints require bearer token authentication. App onboarding is admin-only and performed through the Docora admin dashboard.

Authentication

All requests require an Authorization header with the bearer token you received during onboarding:

Authorization: Bearer docora_abcdef123456...

curl Example

curl -X POST https://your-docora-instance/api/repositories \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer docora_abcdef123456..." \
  -d '{"github_url": "https://github.com/owner/repo"}'

Keep your token secret. The bearer token authenticates all your API calls. Do not expose it in client-side code, logs, or public repositories.

POST /api/repositories

Register a GitHub repository for Docora to monitor. Docora validates the repository exists and is accessible, then begins scanning for files.

POST /api/repositories

Requires: Authorization: Bearer <token>

Request Body

Field	Type	Required	Description
`github_url`	string	Yes	GitHub repository URL (`https://github.com/owner/repo`)
`github_token`	string	No	GitHub personal access token (required for private repos, starts with `ghp_` or `github_pat_`)

{
  "github_url": "https://github.com/owner/repo",
  "github_token": "ghp_xxxxxxxxxxxx"
}

Response (201 Created)

Field	Type	Description
`repository_id`	string	Docora repository identifier
`github_url`	string	Full GitHub URL
`owner`	string	Repository owner
`name`	string	Repository name
`is_private`	boolean	Whether the repository is private
`created_at`	string	ISO 8601 creation timestamp

{
  "repository_id": "repo_abc123def456",
  "github_url": "https://github.com/owner/repo",
  "owner": "owner",
  "name": "repo",
  "is_private": false,
  "created_at": "2025-01-08T12:00:00Z"
}

Error Responses

Status	Description
401	Unauthorized – missing or invalid bearer token
404	Repository not found on GitHub (or token lacks access)
422	Invalid GitHub URL format

Re-registration: Registering a repository your app already watches will unwatch it first and re-register it, triggering a fresh full scan.

DELETE /api/repositories/:repository_id

Stop watching a repository and clean up delivery history for your app.

DELETE /api/repositories/:repository_id

Requires: Authorization: Bearer <token>

Path Parameters

Parameter	Format	Description
`repository_id`	`repo_` + 24 hex characters	Docora repository identifier

Response (204 No Content)

No response body on success.

Error Responses

Status	Description
401	Unauthorized – missing or invalid bearer token
404	Repository not found or not registered for this app

PATCH /api/repositories/:repository_id/token

Update the GitHub personal access token for a watched repository. This resets any error state and circuit breaker, triggering a fresh scan.

PATCH /api/repositories/:repository_id/token

Requires: Authorization: Bearer <token>

Path Parameters

Parameter	Format	Description
`repository_id`	`repo_` + 24 hex characters	Docora repository identifier

Request Body

Field	Type	Required	Description
`github_token`	string	Yes	New GitHub personal access token (starts with `ghp_` or `github_pat_`)

{
  "github_token": "ghp_xxxxxxxxxxxx"
}

Response (200 OK)

Field	Type	Description
`message`	string	`"Token updated successfully"`

{
  "message": "Token updated successfully"
}

Error Responses

Status	Description
401	Unauthorized – missing or invalid bearer token
404	Repository not found or not registered for this app
422	Token cannot access this repository

When to use: If you receive a sync_failed webhook, use this endpoint to rotate the token and restore syncing.

Error Responses

All error responses follow the same structure:

{
  "error": "Description of what went wrong"
}

Common Status Codes

Status	Description
401	Unauthorized – missing or invalid bearer token
404	Resource not found
422	Validation error – invalid input data
500	Internal server error