Agent API

Overview

The Agent API lets you programmatically create and manage AI agent jobs that audit, update, and maintain your documentation. The agent reads your docs, identifies issues (broken links, stale content, OpenAPI drift), and produces actionable suggestions that you can approve or reject before they are committed to your repository.

Base path: https://api.holydocs.com/api/v1/projects/:projectId/agent

All agent endpoints require authentication with the agent:write scope.

Agent jobs run asynchronously on HolyDocs infrastructure. Each job is processed by a dedicated queue worker that orchestrates the LLM, tool calls, and Git operations. You receive results via polling or webhooks.

Create Agent Job

Create a new agent job with a natural language prompt describing what you want the agent to do.

bash
POST /api/v1/projects/:projectId/agent/jobs

Copy as context

bash
curl -X POST "https://api.holydocs.com/api/v1/projects/$PROJECT_ID/agent/jobs" \  -H "Authorization: Bearer $HOLYDOCS_API_KEY" \  -H "Content-Type: application/json" \  -d '{"prompt":"Review API reference pages for broken links","scope":"all"}'

bash
holydocs api post "/projects/$PROJECT_ID/agent/jobs" \  --json '{"prompt":"Review API reference pages for broken links"}'

ts
import { HolyDocs } from '@holydocs/sdk';const client = new HolyDocs({ apiKey: process.env.HOLYDOCS_API_KEY });const { data: job } = await client.agent.createJob(projectId, {  prompt: 'Review API reference pages for broken links',  scope: 'all',});

Path Parameters

Request Body

json
{  "prompt": "Review all API reference pages for broken links and outdated code examples. Suggest fixes for any issues found.",  "scope": "all",  "autoCommit": false}

Response

json
{  "data": {    "id": "job_abc123",    "projectId": "proj_xyz",    "status": "queued",    "prompt": "Review all API reference pages for broken links and outdated code examples. Suggest fixes for any issues found.",    "scope": "all",    "autoCommit": false,    "createdAt": "2026-04-11T10:00:00Z"  }}

bash
curl -X POST "https://api.holydocs.com/api/v1/projects/proj_abc123/agent/jobs" \  -H "Authorization: Bearer hd_a1b2c3d4e5f67890a1b2c3d4e5f67890" \  -H "Content-Type: application/json" \  -d '{    "prompt": "Check all pages for broken links and suggest fixes",    "scope": "all",    "autoCommit": false  }'

javascript
const response = await fetch(  'https://api.holydocs.com/api/v1/projects/proj_abc123/agent/jobs',  {    method: 'POST',    headers: {      'Authorization': 'Bearer hd_a1b2c3d4e5f67890a1b2c3d4e5f67890',      'Content-Type': 'application/json'    },    body: JSON.stringify({      prompt: 'Check all pages for broken links and suggest fixes',      scope: 'all',      autoCommit: false    })  });const { data } = await response.json();console.log(`Agent job ${data.id} created with status: ${data.status}`);

python
import requestsresponse = requests.post(    "https://api.holydocs.com/api/v1/projects/proj_abc123/agent/jobs",    headers={"Authorization": "Bearer hd_a1b2c3d4e5f67890a1b2c3d4e5f67890"},    json={        "prompt": "Check all pages for broken links and suggest fixes",        "scope": "all",        "autoCommit": False    })data = response.json()["data"]print(f"Agent job {data['id']} created with status: {data['status']}")

Example Prompts

text
Check all internal and external links across the documentation. Report anybroken links, redirect chains, or links pointing to deprecated pages.Suggest replacements where possible.

text
Compare the OpenAPI spec at /openapi.yaml with the API reference pages.Identify any endpoints, parameters, or response schemas that are documentedbut no longer exist in the spec, or exist in the spec but are not documented.

text
Review all pages for consistent use of admonitions, code block language tags,and heading hierarchy. Flag any pages that skip heading levels or useinconsistent callout types for similar content.

text
Identify pages that reference deprecated features, outdated version numbers,or APIs that have been removed. Suggest updated content or mark pages forreview.

text
Review the /api/authentication page specifically. Check that all code exampleswork, error codes are accurate, and the rate limit table matches the currentplan tiers.

List Agent Jobs

Retrieve a list of agent jobs for a project, ordered by most recent first.

bash
GET /api/v1/projects/:projectId/agent/jobs

Query Parameters

Response

json
{  "data": [    {      "id": "job_abc123",      "status": "completed",      "prompt": "Check all pages for broken links and suggest fixes",      "scope": "all",      "suggestionsCount": 7,      "approvedCount": 5,      "rejectedCount": 1,      "pendingCount": 1,      "tokensUsed": 45000,      "duration": 120,      "createdAt": "2026-04-11T10:00:00Z",      "completedAt": "2026-04-11T10:02:00Z"    },    {      "id": "job_def456",      "status": "running",      "prompt": "Review API reference for OpenAPI drift",      "scope": "section",      "scopePath": "/api",      "suggestionsCount": 3,      "approvedCount": 0,      "rejectedCount": 0,      "pendingCount": 3,      "tokensUsed": 28000,      "duration": null,      "createdAt": "2026-04-11T10:05:00Z",      "completedAt": null    }  ],  "meta": {    "total": 24,    "page": 1,    "perPage": 20,    "totalPages": 2  }}

Get Job Details

Retrieve detailed information about a specific job, including all suggestions.

bash
GET /api/v1/projects/:projectId/agent/jobs/:jobId

Response

json
{  "data": {    "id": "job_abc123",    "projectId": "proj_xyz",    "status": "completed",    "prompt": "Check all pages for broken links and suggest fixes",    "scope": "all",    "autoCommit": false,    "tokensUsed": 45000,    "duration": 120,    "createdAt": "2026-04-11T10:00:00Z",    "completedAt": "2026-04-11T10:02:00Z",    "toolCalls": [      { "tool": "list_pages", "duration": 0.8 },      { "tool": "read_page", "input": { "path": "/api/authentication" }, "duration": 0.3 },      { "tool": "check_links", "input": { "path": "/api/authentication" }, "duration": 2.1 },      { "tool": "read_page", "input": { "path": "/quickstart" }, "duration": 0.3 },      { "tool": "check_links", "input": { "path": "/quickstart" }, "duration": 1.8 },      { "tool": "suggest_edit", "input": { "path": "/quickstart", "description": "Fix broken link to old migration guide" }, "duration": 0.1 }    ],    "suggestions": [      {        "id": "sug_001",        "status": "pending",        "pagePath": "/quickstart",        "type": "edit",        "title": "Fix broken link to migration guide",        "description": "The link to `/migration` returns 404. The page has moved to `/cli/migrate`.",        "diff": "- See the [Migration Guide](/migration) for upgrading.\n+ See the [Migration Guide](/cli/migrate) for upgrading.",        "createdAt": "2026-04-11T10:01:45Z"      },      {        "id": "sug_002",        "status": "approved",        "pagePath": "/api/authentication",        "type": "edit",        "title": "Update rate limit values",        "description": "The Business plan rate limit is listed as 2,000/min but should be 3,000/min.",        "diff": "- | Business | 2,000 |\n+ | Business | 3,000 |",        "approvedAt": "2026-04-11T10:10:00Z",        "createdAt": "2026-04-11T10:01:30Z"      }    ]  }}

Agent Tools

The agent has access to seven specialized tools. It selects and chains these tools autonomously based on the prompt you provide.

json
{  "path": "/quickstart",  "title": "Fix broken link to migration guide",  "description": "The link to /migration returns 404. The page has moved to /cli/migrate.",  "oldContent": "See the [Migration Guide](/migration) for upgrading.",  "newContent": "See the [Migration Guide](/cli/migrate) for upgrading."}

json
{  "path": "/quickstart",  "content": "...full updated page content...",  "commitMessage": "fix: update broken link to migration guide"}

The commit_fix tool is only available when the job is created with autoCommit: true. Even with auto-commit enabled, the agent applies guardrails: it will not delete pages, modify navigation structure, or make changes affecting more than 20% of a page's content without creating a suggestion for review instead.

Approve Suggestion

Approve a pending suggestion. If the project has a connected Git repository, the approved edit is committed to a branch and a pull request is created.

bash
POST /api/v1/projects/:projectId/agent/suggestions/:id/approve

Path Parameters

Request Body

json
{  "commitMessage": "fix: update broken link to migration guide",  "branch": "agent/fix-broken-links"}

Response

json
{  "data": {    "id": "sug_001",    "status": "approved",    "commitSha": "a1b2c3d4",    "branch": "agent/fix-broken-links",    "pullRequestUrl": "https://github.com/myorg/docs/pull/42",    "approvedAt": "2026-04-11T10:15:00Z"  }}

Reject Suggestion

Reject a pending suggestion with an optional reason.

bash
POST /api/v1/projects/:projectId/agent/suggestions/:id/reject

Request Body

json
{  "reason": "The current link is intentional — it redirects to the new page."}

Response

json
{  "data": {    "id": "sug_001",    "status": "rejected",    "reason": "The current link is intentional — it redirects to the new page.",    "rejectedAt": "2026-04-11T10:15:00Z"  }}

Job Statuses

Agent Limits by Plan

Agent jobs on the Free plan are limited to 10 pages per job and 5 jobs per month. Upgrade to Pro or above for production-scale documentation maintenance.

Webhook Events

Subscribe to agent events via outbound webhooks:

Error Codes