API Reference

The Ovvoc REST API lets you programmatically manage repositories, trigger jobs, and query update data. Available on the Growth plan and above.

Authentication

All API requests require a JWT token. Include it as a Bearer token in theAuthorization header, or use the HttpOnly cookie set during login. Tokens expire after 24 hours.

curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  https://api.ovvoc.com/api/v1/repos

Health endpoints

These endpoints are unauthenticated and used for monitoring:

# Request
curl https://api.ovvoc.com/health

# Response (200 OK)
{
  "status": "ok"
}

# Request
curl https://api.ovvoc.com/ready

# Response (200 OK)
{
  "status": "ready",
  "database": "connected",
  "worker_pool": "running"
}

Repositories

GET /api/v1/repos

List all repositories for the authenticated user.

# Response (200 OK)
{
  "repositories": [
    {
      "id": "repo_abc123",
      "name": "acme/api-server",
      "status": "monitoring",
      "dependency_count": 42,
      "outdated_count": 4,
      "last_scan": "2026-02-10T12:00:00Z"
    }
  ]
}

GET /api/v1/repos/:id

Get detailed information about a specific repository.

PUT /api/v1/repos/:id/settings

Update repository settings (schedule, branch strategy, filters).

# Request
curl -X PUT \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "schedule": "daily",
    "target_branch": "main",
    "exclude_packages": ["@internal/legacy"]
  }' \
  https://api.ovvoc.com/api/v1/repos/repo_abc123/settings

# Response (200 OK)
{
  "id": "repo_abc123",
  "settings": {
    "schedule": "daily",
    "target_branch": "main",
    "exclude_packages": ["@internal/legacy"]
  }
}

Jobs

GET /api/v1/jobs

List all pipeline jobs. Supports query parameters for filtering.

# Request with filters
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  "https://api.ovvoc.com/api/v1/jobs?repo_id=repo_abc123&status=completed"

# Response (200 OK)
{
  "jobs": [
    {
      "id": "job_1847",
      "repo_id": "repo_abc123",
      "dependency": "express",
      "from_version": "4.21.0",
      "to_version": "5.2.1",
      "status": "completed",
      "confidence": 0.95,
      "duration_seconds": 42,
      "created_at": "2026-02-10T14:00:00Z",
      "completed_at": "2026-02-10T14:00:42Z"
    }
  ]
}

GET /api/v1/jobs/:id

Get full job detail including stage-by-stage breakdown.

POST /api/v1/jobs

Manually trigger a job for a specific dependency update.

# Request
curl -X POST \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "repo_id": "repo_abc123",
    "dependency": "express",
    "target_version": "5.2.1"
  }' \
  https://api.ovvoc.com/api/v1/jobs

# Response (201 Created)
{
  "id": "job_1850",
  "status": "queued",
  "dependency": "express",
  "target_version": "5.2.1"
}

Updates

GET /api/v1/updates

List all detected dependency updates across repositories.

GET /api/v1/updates/:id

Get details for a specific update including category and severity.

Pull Requests

GET /api/v1/pull-requests

List all pull requests created by Ovvoc.

GET /api/v1/pull-requests/:id

Get details for a specific PR including confidence score and GitHub URL.

Billing

GET /api/v1/billing

Get current plan and billing information.

GET /api/v1/billing/usage

Get usage statistics for the current billing period.

# Response (200 OK)
{
  "period_start": "2026-02-01T00:00:00Z",
  "period_end": "2026-02-28T23:59:59Z",
  "repos_monitored": 5,
  "jobs_completed": 47,
  "jobs_failed": 3,
  "prs_created": 44,
  "prs_merged": 38
}

Webhooks

GET /api/v1/webhooks

List configured webhook endpoints.

POST /api/v1/webhooks

Create a new webhook endpoint.

# Request
curl -X POST \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks/ovvoc",
    "events": ["job.completed", "job.failed", "pr.created"],
    "secret": "your-signing-secret"
  }' \
  https://api.ovvoc.com/api/v1/webhooks

# Response (201 Created)
{
  "id": "wh_xyz789",
  "url": "https://your-server.com/webhooks/ovvoc",
  "events": ["job.completed", "job.failed", "pr.created"],
  "active": true
}

DELETE /api/v1/webhooks/:id

Delete a webhook endpoint.

Error handling

All errors return a consistent JSON structure:

# 400 Bad Request
{
  "error": "Invalid repository ID",
  "code": "INVALID_REPO_ID"
}

# 401 Unauthorized
{
  "error": "Token expired",
  "code": "TOKEN_EXPIRED"
}

# 404 Not Found
{
  "error": "Job not found",
  "code": "NOT_FOUND",
  "details": {
    "job_id": "job_9999"
  }
}

# 429 Too Many Requests
{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMITED",
  "details": {
    "retry_after": 30
  }
}

Rate limiting

API requests are rate-limited to 100 requests per minute per authenticated user. Rate limit information is included in response headers:

• X-RateLimit-Limit: 100
• X-RateLimit-Remaining: Remaining requests in the window
• X-RateLimit-Reset: Unix timestamp when the window resets

Authentication details

The Ovvoc API uses JWT (JSON Web Tokens) for authentication. Tokens are obtained through the GitHub OAuth flow and provide access to all API endpoints.

Obtaining a token

Tokens are issued automatically when you sign in via the Ovvoc dashboard using GitHub OAuth. The OAuth flow redirects to GitHub for authorization, then returns to Ovvoc with an authorization code that is exchanged for a JWT.

Token lifetime

JWT tokens expire after 24 hours. After expiration, you will receive a 401 Unauthorized response. To refresh your token, re-authenticate via the GitHub OAuth flow by visiting the sign-in page.

Using the token

Include the token in the Authorization header as a Bearer token:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

For browser-based sessions, Ovvoc also sets an HttpOnly cookie containing the JWT. This cookie is sent automatically with every request from the dashboard and does not require manual header management. The cookie is secure (HTTPS only), httpOnly (not accessible to JavaScript), and sameSite strict.

Core endpoints reference

Here is a complete reference of all available API endpoints with their methods, paths, and purposes:

All endpoints return JSON responses and require authentication unless otherwise noted (the /health and /ready endpoints documented above are unauthenticated).

Rate limiting details

The API enforces rate limits to ensure fair usage and system stability. Here are the specifics:

• Default limit: 100 requests per minute per authenticated user. This is a sliding window — each request consumes one slot that is replenished after 60 seconds.
• Burst capacity: Up to 20 concurrent requests are allowed. If you send more than 20 simultaneous requests, excess requests will be queued or rejected with a 429 status.
• Rate limit headers: Every response includes three headers:
  • X-RateLimit-Limit — the maximum number of requests per window (100)
  • X-RateLimit-Remaining — how many requests you have left in the current window
  • X-RateLimit-Reset — Unix timestamp (seconds) when the current window resets
• 429 responses: When you exceed the rate limit, the API returns a 429 Too Many Requests response with a retry_after field in the JSON body indicating how many seconds to wait before retrying.

Pagination

All list endpoints support pagination via query parameters. The response includes metadata to help you navigate through large result sets:

• Response format: List endpoints return an object with a data array containing the items and a total field with the total count of matching records.
• Default limit: If no limit parameter is specified, the API returns up to 50 items per request.
• Pagination parameters: Use ?limit=N&offset=M to control pagination. limit sets the maximum number of items to return (1–100). offset skips the first M items (default: 0).
• Maximum limit: The maximum value for limit is 100 items per request. Requests with a higher value will be capped at 100.

# Fetch page 1 (items 0-49)
curl -H "Authorization: Bearer TOKEN" \
  "https://api.ovvoc.com/api/v1/jobs?limit=50&offset=0"

# Fetch page 2 (items 50-99)
curl -H "Authorization: Bearer TOKEN" \
  "https://api.ovvoc.com/api/v1/jobs?limit=50&offset=50"

# Response format
{
  "data": [
    { "id": "job_1847", "status": "completed", ... },
    { "id": "job_1848", "status": "failed", ... }
  ],
  "total": 247
}

Error response reference

All error responses follow a consistent JSON format with an error string describing what went wrong. Some errors include additional fields for context:

When building API integrations, always check the HTTP status code first, then parse the JSON error field for a human-readable description. For 429 responses, implement exponential backoff using the retry_after value.