Projects

GET/projectsread

Every project you own, each with its settings and its latest crawl.

curl http://localhost:9000/api/v1/projects -H "Authorization: Bearer $KEY"

{ "projects": [ { "id": 1, "url": "https://example.com", ... } ] }

POST/projectswrite

Adds a project. The body takes the project settings; only url is required, and every toggle is off unless you send it.

curl -X POST http://localhost:9000/api/v1/projects -H "Authorization: Bearer $KEY" \
  -d '{"url": "https://example.com", "crawl_sitemap": true}'

Answers 201 Created with the project, and its address in the Location header:

{
  "id": 1,
  "url": "https://example.com",
  "host": "example.com",
  "created": "2026-09-29T12:33:15Z",
  "user_agent": "Mozilla/5.0 (compatible; ...)",
  "settings": {
    "ignore_robots_txt": false,
    "follow_nofollow": false,
    "include_noindex": false,
    "crawl_sitemap": true,
    "allow_subdomains": false,
    "check_external_links": false,
    "archive": false,
    "basic_auth": false,
    "render_javascript": false
  },
  "last_crawl": null
}

last_crawl is null until the project is crawled. You cannot have two projects for the same URL: a second one answers 409 project_exists, with the existing project's address in Location.

GET/projects/{id}read

One project, in the same shape. This is the call to poll while a crawl runs: last_crawl.crawling turns false when it is done.

"last_crawl": {
  "id": 3,
  "start": "2026-09-29T12:33:15Z",
  "end": "2026-09-29T12:35:02Z",
  "crawling": false,
  "total_urls": 87,
  "total_issues": 41,
  "critical_issues": 2,
  "alert_issues": 12,
  "warning_issues": 27
}

end is null while the crawl is still running.

PATCH/projects/{id}write

Changes settings. Send only the fields you want to change; the others stay as they are. Answers 200 with the updated project.

curl -X PATCH http://localhost:9000/api/v1/projects/1 -H "Authorization: Bearer $KEY" \
  -d '{"check_external_links": true, "crawl_sitemap": true}'

• Changes apply from the next crawl. A crawl already running carries on with what it started with.
• url can be changed too, for a site that moved; it must not be the URL of another of your projects (409 project_exists).
• "user_agent": "" goes back to the default user agent.
• "archive": false deletes the archive already stored for the project.
• If any field is refused, nothing is changed.