Skip to main content

​
Overview

The Adapt API is a RESTful HTTP API that enables you to programmatically manage web scraping jobs, monitor crawl progress, and analyse results. All endpoints return JSON responses with a consistent format.

​
Base URLs

Adapt uses different base URLs depending on your environment:
​
Local Development
string
http://localhost:8080
Use this URL when running Adapt locally for testing and development.
​
Production
string
https://adapt.app.goodnative.co
The live application URL for production API access.
The marketing website at https://goodnative.co does not serve API endpoints.

​
Versioning

All API endpoints are versioned under the /v1/ prefix to ensure backward compatibility: 
https://adapt.app.goodnative.co/v1/jobs
When breaking changes are introduced, a new version (e.g., /v2/) will be released while maintaining support for existing versions.

​
Request Format

All POST, PUT, and PATCH requests must include a Content-Type header: 
Content-Type: application/json
Request bodies should be valid JSON: 
{
  "domain": "example.com",
  "options": {
    "use_sitemap": true,
    "max_pages": 100
  }
}

​
Response Format

All API responses follow a standardised format with consistent structure.

​
Success Response

Successful requests return a 200 or 201 status code: 
{
  "status": "success",
  "data": {
    "id": "job_123abc",
    "domain": "example.com",
    "status": "running"
  },
  "message": "Job created successfully",
  "request_id": "req_a1b2c3d4"
}
​
status
string
required
Always "success" for successful responses.
​
data
object
The response payload. Structure varies by endpoint.
​
message
string
Human-readable description of the operation result.
​
request_id
string
Unique identifier for this request. Include this when reporting issues.

​
Error Response

Failed requests return appropriate HTTP status codes (400-599): 
{
  "status": 400,
  "message": "Invalid job configuration",
  "code": "VALIDATION_ERROR",
  "request_id": "req_a1b2c3d4"
}
​
status
integer
required
HTTP status code (400, 401, 403, 404, 500, etc.).
​
message
string
required
Human-readable error description.
​
code
string
required
Machine-readable error code for programmatic handling.
​
request_id
string
Unique request identifier for debugging and support.
See the Errors page for a complete list of error codes.

​
Rate Limiting

The API implements rate limiting to ensure fair usage:
  • IP-based: 5 requests per second per IP address
  • Burst capacity: 5 requests
When you exceed the rate limit, the API returns a 429 Too Many Requests response: 
{
  "status": 429,
  "message": "Too many requests, please retry shortly",
  "code": "RATE_LIMIT_EXCEEDED",
  "request_id": "req_a1b2c3d4"
}
The response includes a Retry-After header indicating how many seconds to wait: 
Retry-After: 3

​
CORS Support

The API implements CORS (Cross-Origin Resource Sharing) to allow browser-based applications to make requests:
  • Preflight requests are handled automatically
  • Appropriate CORS headers are included in responses
  • Authentication tokens are supported in cross-origin requests

​
Health Checks

Two health check endpoints are available without authentication:
​
/health
GET
Basic service health check
​
/health/db
GET
Database connectivity health check
curl https://adapt.app.goodnative.co/health

{
  "status": "healthy",
  "timestamp": "2026-03-03T12:34:56Z",
  "service": "adapt-api",
  "version": "1.0.0"
}

​
Getting Started

  1. Authenticate: Obtain a JWT token from Supabase Auth or create an API key
  2. Make requests: Include your token in the Authorization header
  3. Handle responses: Check the status field and handle errors appropriately
curl -X POST https://adapt.app.goodnative.co/v1/jobs \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "example.com",
    "options": {
      "use_sitemap": true,
      "max_pages": 100
    }
  }'
Next, learn about authentication or explore the error codes.

Build docs developers (and LLMs) love

Get started for freeTalk to us