API Reference

Auto-generated

V1

API reference for v1 endpoints.

Auto-generated

This page was generated from the OpenAPI spec. Runmake generate-docs to refresh after spec changes.

POST /api/v1/analytics/events

POST

/api/v1/analytics/events

Ingest Beacon Events

Parameters

Name	Type	Required	Description
events	`object[]`	Required	Events

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/analytics/events \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": []
  }'

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/analytics/funnels

GET

/api/v1/analytics/funnels

List Funnels

Parameters

Name	Type	Required	Description
args	`string`	Required	args
kwargs	`string`	Required	kwargs

Request Example

Bash

curl -X GET 'https://api.alterlab.io/api/v1/analytics/funnels?args=<args>&kwargs=<kwargs>' \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/analytics/funnels-all

GET

/api/v1/analytics/funnels-all

Get All Funnel Stats

Parameters

Name	Type	Required	Description
days	`integer`	Optional	daysDefault: `30`
args	`string`	Required	args
kwargs	`string`	Required	kwargs

Request Example

Bash

curl -X GET 'https://api.alterlab.io/api/v1/analytics/funnels-all?args=<args>&kwargs=<kwargs>' \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/analytics/funnels/{funnel_name}

GET

/api/v1/analytics/funnels/{funnel_name}

Get Funnel Stats

Parameters

Name	Type	Required	Description
funnel_name	`string`	Required	funnel_name
days	`integer`	Optional	daysDefault: `30`
args	`string`	Required	args
kwargs	`string`	Required	kwargs

Request Example

Bash

curl -X GET 'https://api.alterlab.io/api/v1/analytics/funnels/<funnel_name>?args=<args>&kwargs=<kwargs>' \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/announcement/active

GET

/api/v1/announcement/active

Get Active Announcement

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/announcement/active \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "enabled": true,
  "text": "example",
  "cta": "example",
  "style": "example",
  "version": 0
}

POST /api/v1/blog/comments

POST

/api/v1/blog/comments

Submit Comment

Parameters

Name	Type	Required	Description
post_id	`string`	Required	Post Id
parent_id	`string`	Optional	parent_id
content	`string`	Required	Content
author_name	`string`	Optional	author_name
author_email	`string`	Optional	author_email
author_website	`string`	Optional	author_website
website_url	`string`	Optional	website_url

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/blog/comments \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "post_id": "example_post_id",
    "content": "example_content"
  }'

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/blog/feed.xml

GET

/api/v1/blog/feed.xml

Rss Feed

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/blog/feed.xml \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

POST /api/v1/blog/posts/{slug}/react

POST

/api/v1/blog/posts/{slug}/react

React To Post

Parameters

Name	Type	Required	Description
slug	`string`	Required	slug

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/blog/posts/<slug>/react \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/blog/posts/{slug}/reactions

GET

/api/v1/blog/posts/{slug}/reactions

Get Reactions

Parameters

Name	Type	Required	Description
slug	`string`	Required	slug

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/blog/posts/<slug>/reactions \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/dashboard/detailed-logs

GET

/api/v1/dashboard/detailed-logs

Get Detailed Logs

Parameters

Name	Type	Required	Description
days	`integer`	Optional	days
hours	`integer`	Optional	hours
limit	`integer`	Optional	limitDefault: `100`
offset	`integer`	Optional	offsetDefault: `0`
source	`string`	Optional	Filter by source: playground (web UI), api (API calls), or crawl (requests originating from a crawl job)
group_by	`string`	Optional	Group results by a field. Supported: 'crawl_id' — returns aggregated summaries (total pages, credits, domain, time range) per crawl.
group_crawls	`boolean`	Optional	When true, pagination counts crawl groups as single entries instead of raw rows. Returns all child rows for each group so the frontend can expand them.Default: `False`
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/dashboard/detailed-logs \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/dashboard/domain-analytics

GET

/api/v1/dashboard/domain-analytics

Get Domain Analytics

Parameters

Name	Type	Required	Description
days	`integer`	Optional	days
hours	`integer`	Optional	hours
limit	`integer`	Optional	limitDefault: `20`
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/dashboard/domain-analytics \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "domains": [],
  "total_domains": 0
}

GET /api/v1/dashboard/domain-analytics/{domain}

GET

/api/v1/dashboard/domain-analytics/{domain}

Get Domain Detail

Parameters

Name	Type	Required	Description
domain	`string`	Required	domain
days	`integer`	Optional	days
hours	`integer`	Optional	hours
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/dashboard/domain-analytics/<domain> \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "domain": "example",
  "total_requests": 0,
  "successful_requests": 0,
  "failed_requests": 0,
  "success_rate": 0,
  "total_credits": 0
}

GET /api/v1/dashboard/domain-timeseries/{domain}

GET

/api/v1/dashboard/domain-timeseries/{domain}

Get Domain Timeseries

Parameters

Name	Type	Required	Description
domain	`string`	Required	domain
days	`integer`	Optional	days
hours	`integer`	Optional	hours
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/dashboard/domain-timeseries/<domain> \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "data": [],
  "period_start": "example",
  "period_end": "example"
}

GET /api/v1/dashboard/endpoint-stats

GET

/api/v1/dashboard/endpoint-stats

Get Endpoint Type Stats

Parameters

Name	Type	Required	Description
days	`integer`	Optional	days
hours	`integer`	Optional	hours
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/dashboard/endpoint-stats \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "data": [],
  "total_requests": 0,
  "total_credits": 0
}

GET /api/v1/dashboard/endpoint-timeseries

GET

/api/v1/dashboard/endpoint-timeseries

Get Endpoint Type Timeseries

Parameters

Name	Type	Required	Description
days	`integer`	Optional	days
hours	`integer`	Optional	hours
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/dashboard/endpoint-timeseries \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "data": [],
  "period_start": "example",
  "period_end": "example"
}

GET /api/v1/dashboard/geo-distribution

GET

/api/v1/dashboard/geo-distribution

Get Geo Distribution

Parameters

Name	Type	Required	Description
days	`integer`	Optional	days
hours	`integer`	Optional	hours
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/dashboard/geo-distribution \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "data": [],
  "total_requests": 0
}

GET /api/v1/dashboard/hourly-patterns

GET

/api/v1/dashboard/hourly-patterns

Get Hourly Patterns

Parameters

Name	Type	Required	Description
days	`integer`	Optional	days
hours	`integer`	Optional	hours
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/dashboard/hourly-patterns \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "data": []
}

GET /api/v1/dashboard/jobs

GET

/api/v1/dashboard/jobs

Get Jobs Paginated

Parameters

Name	Type	Required	Description
limit	`integer`	Optional	limitDefault: `20`
offset	`integer`	Optional	offsetDefault: `0`
status	`string`	Optional	Filter by status
mode	`string`	Optional	Filter by mode (light, js, pdf, ocr)
search	`string`	Optional	Search in URL
source	`string`	Optional	Filter by source (playground, api)
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/dashboard/jobs \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "jobs": [],
  "total": 0,
  "limit": 0,
  "offset": 0,
  "has_more": true
}

GET /api/v1/dashboard/jobs/{job_id}

GET

/api/v1/dashboard/jobs/{job_id}

Get Job Detail

Parameters

Name	Type	Required	Description
job_id	`string`	Required	job_id
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/dashboard/jobs/<job_id> \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "id": "example",
  "url": "example",
  "mode": "example",
  "status": "example",
  "credits_used": 0,
  "created_at": "example"
}

GET /api/v1/dashboard/peak-hours

GET

/api/v1/dashboard/peak-hours

Get Peak Hours

Parameters

Name	Type	Required	Description
days	`integer`	Optional	days
hours	`integer`	Optional	hours
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/dashboard/peak-hours \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "data": []
}

GET /api/v1/dashboard/recent-jobs

GET

/api/v1/dashboard/recent-jobs

Get Recent Jobs

Parameters

Name	Type	Required	Description
limit	`integer`	Optional	limitDefault: `10`
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/dashboard/recent-jobs \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/dashboard/request-types

GET

/api/v1/dashboard/request-types

Get Request Types

Parameters

Name	Type	Required	Description
days	`integer`	Optional	days
hours	`integer`	Optional	hours
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/dashboard/request-types \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "data": [],
  "total_requests": 0
}

GET /api/v1/dashboard/stats

GET

/api/v1/dashboard/stats

Get Dashboard Stats

Parameters

Name	Type	Required	Description
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/dashboard/stats \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "credits_available": 0,
  "credits_change_percent": 0,
  "total_requests_month": 0,
  "requests_change_percent": 0,
  "cache_hit_rate": 0,
  "avg_response_time_ms": "example"
}

GET /api/v1/dashboard/status-codes

GET

/api/v1/dashboard/status-codes

Get Status Codes

Parameters

Name	Type	Required	Description
days	`integer`	Optional	days
hours	`integer`	Optional	hours
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/dashboard/status-codes \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "individual": [],
  "grouped": {}
}

GET /api/v1/dashboard/top-consumers

GET

/api/v1/dashboard/top-consumers

Get Top Consumers

Parameters

Name	Type	Required	Description
days	`integer`	Optional	days
hours	`integer`	Optional	hours
limit	`integer`	Optional	limitDefault: `10`
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/dashboard/top-consumers \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "top_domains": [],
  "top_urls": []
}

GET /api/v1/dashboard/top-endpoints

GET

/api/v1/dashboard/top-endpoints

Get Top Endpoints

Parameters

Name	Type	Required	Description
days	`integer`	Optional	days
hours	`integer`	Optional	hours
limit	`integer`	Optional	limitDefault: `10`
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/dashboard/top-endpoints \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "data": []
}

GET /api/v1/dashboard/usage-timeseries

GET

/api/v1/dashboard/usage-timeseries

Get Usage Timeseries

Parameters

Name	Type	Required	Description
days	`integer`	Optional	days
hours	`integer`	Optional	hours
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/dashboard/usage-timeseries \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "data": [],
  "period_start": "example",
  "period_end": "example",
  "total_days": 0
}

GET /api/v1/favicon

GET

/api/v1/favicon

Get Favicon

Parameters

Name	Type	Required	Description
domain	`string`	Required	Domain to get favicon for (e.g., 'example.com')
size	`integer`	Optional	Favicon size in pixelsDefault: `32`

Request Example

Bash

curl -X GET 'https://api.alterlab.io/api/v1/favicon?domain=<domain>' \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/favicon/batch

GET

/api/v1/favicon/batch

Get Favicons Batch

Parameters

Name	Type	Required	Description
domains	`string`	Required	Comma-separated list of domains
size	`integer`	Optional	Favicon size in pixelsDefault: `32`

Request Example

Bash

curl -X GET 'https://api.alterlab.io/api/v1/favicon/batch?domains=<domains>' \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

POST /api/v1/feedback/scrape

POST

/api/v1/feedback/scrape

Submit Scrape Feedback

Parameters

Name	Type	Required	Description
job_id	`string`	Required	Job ID of the scrape request
issue_type	`"captcha_page" \| "incomplete_scrape" \| "blocked" \| "wrong_content" \| "slow_response" \| "extraction_error" \| "encoding_error" \| "other"`	Required	Types of issues users can report about scrape results. These map to the UI dropdown options in the Playground.
description	`string`	Optional	description
expected_content	`string`	Optional	expected_content

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/feedback/scrape \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "job_id": "example_job_id",
    "issue_type": "..."
  }'

Response Example

JSON

{
  "feedback_id": "example",
  "status": "example",
  "message": "example",
  "analysis_queued": true,
  "support_ticket_id": "example",
  "support_ticket_ref": "example"
}

GET /api/v1/health

GET

/api/v1/health

Health Check V1

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/health \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "example",
  "timestamp": "example",
  "version": "example"
}

GET /api/v1/health/jobs

GET

/api/v1/health/jobs

Job Health Check

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/health/jobs \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/health/live

GET

/api/v1/health/live

Liveness Check

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/health/live \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/health/ocr

GET

/api/v1/health/ocr

Ocr Health Check

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/health/ocr \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "available": true,
  "tesseract_version": "example",
  "pillow_version": "example",
  "languages": "example",
  "message": "example"
}

GET /api/v1/health/ready

GET

/api/v1/health/ready

Readiness Check

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/health/ready \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/notifications/active

GET

/api/v1/notifications/active

Get Active Notifications

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/notifications/active \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "notifications": []
}

POST /api/v1/notifications/dismiss

POST

/api/v1/notifications/dismiss

Dismiss Notification

Parameters

Name	Type	Required	Description
notification_id	`string`	Required	Notification Id

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/notifications/dismiss \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "notification_id": "example_notification_id"
  }'

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/notifications/history

GET

/api/v1/notifications/history

Get Notification History

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/notifications/history \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "notifications": []
}

POST /api/v1/oauth/authorize

POST

/api/v1/oauth/authorize

Oauth Authorize

Parameters

Name	Type	Required	Description
client_id	`string`	Required	Client Id
redirect_uri	`string`	Required	Redirect Uri
state	`string`	Required	State
scope	`string`	Optional	ScopeDefault: `scrape`
source	`string`	Optional	SourceDefault: `unknown`

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/oauth/authorize \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "example_client_id",
    "redirect_uri": "example_redirect_uri",
    "state": "example_state",
    "scope": "example_scope",
    "source": "example_source"
  }'

Response Example

JSON

{
  "code": "example",
  "state": "example"
}

POST /api/v1/oauth/token

POST

/api/v1/oauth/token

Oauth Token

Parameters

Name	Type	Required	Description
grant_type	`string`	Required	Must be 'authorization_code'
code	`string`	Required	Authorization code from /oauth/authorize
client_id	`string`	Required	Client Id
client_secret	`string`	Required	Client Secret
redirect_uri	`string`	Required	Redirect Uri

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/oauth/token \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "example_grant_type",
    "code": "example_code",
    "client_id": "example_client_id",
    "client_secret": "example_client_secret",
    "redirect_uri": "example_redirect_uri"
  }'

Response Example

JSON

{
  "access_token": "example",
  "token_type": "example",
  "scope": "example"
}

POST /api/v1/reports

POST

/api/v1/reports

Create Report

Parameters

Name	Type	Required	Description
domain	`string`	Required	Domain
url	`string`	Required	Url
title	`string`	Optional	title
score	`integer`	Required	Score
signals	`object[]`	Optional	Signals
anti_bot_stack	`object[]`	Optional	Anti Bot Stack
tech_stack	`object`	Optional	tech_stack
pagination	`object`	Optional	pagination
api_endpoints	`object[]`	Optional	Api Endpoints
meta	`object`	Optional	meta
cookie_count	`integer`	Optional	Cookie CountDefault: `0`
has_login_wall	`boolean`	Optional	Has Login WallDefault: `False`
has_cookie_gate	`boolean`	Optional	Has Cookie GateDefault: `False`
estimated_credits	`object`	Optional	estimated_credits

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/reports \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "example_domain",
    "url": "example_url",
    "score": 0
  }'

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/reports/{report_id}

GET

/api/v1/reports/{report_id}

Get Report

Parameters

Name	Type	Required	Description
report_id	`string`	Required	report_id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/reports/<report_id> \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/status

GET

/api/v1/status

Public Status

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/status \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "overall_status": "example",
  "services": [],
  "timestamp": "example",
  "uptime_percentage": 0
}

GET /api/v1/support/attachments/{attachment_id}

GET

/api/v1/support/attachments/{attachment_id}

Download a file attachment

Parameters

Name	Type	Required	Description
attachment_id	`string`	Required	attachment_id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/support/attachments/<attachment_id> \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

DELETE /api/v1/support/attachments/{attachment_id}

DELETE

/api/v1/support/attachments/{attachment_id}

Delete a file attachment (admin only)

Parameters

Name	Type	Required	Description
attachment_id	`string`	Required	attachment_id

Request Example

Bash

curl -X DELETE https://api.alterlab.io/api/v1/support/attachments/<attachment_id> \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/support/categories

GET

/api/v1/support/categories

List active ticket categories

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/support/categories \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "categories": [],
  "total": 0
}

GET /api/v1/support/kb/search

GET

/api/v1/support/kb/search

Search knowledge base articles

Parameters

Name	Type	Required	Description
q	`string`	Required	Search query
limit	`integer`	Optional	Max results to returnDefault: `3`

Request Example

Bash

curl -X GET 'https://api.alterlab.io/api/v1/support/kb/search?q=<q>' \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "query": "example",
  "results": [],
  "total": 0
}

GET /api/v1/support/kb/{slug}

GET

/api/v1/support/kb/{slug}

Get a published KB article by slug

Parameters

Name	Type	Required	Description
slug	`string`	Required	slug

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/support/kb/<slug> \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "id": "example",
  "title": "example",
  "slug": "example",
  "body": "example",
  "category": "example",
  "tags": []
}

POST /api/v1/support/kb/{slug}/helpful

POST

/api/v1/support/kb/{slug}/helpful

Record whether an article was helpful

Parameters

Name	Type	Required	Description
slug	`string`	Required	slug
helpful	`boolean`	Required	True = helpful, False = not helpful

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/support/kb/<slug>/helpful \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "helpful": false
  }'

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/support/preferences

GET

/api/v1/support/preferences

Get notification preferences

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/support/preferences \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "user_id": "example",
  "notification_settings": "example",
  "updated_at": "example"
}

PATCH /api/v1/support/preferences

PATCH

/api/v1/support/preferences

Update notification preferences

Parameters

Name	Type	Required	Description
email_admin_reply	`boolean`	Optional	email_admin_reply
email_status_change	`boolean`	Optional	email_status_change
email_resolved	`boolean`	Optional	email_resolved

Request Example

Bash

curl -X PATCH https://api.alterlab.io/api/v1/support/preferences \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "user_id": "example",
  "notification_settings": "example",
  "updated_at": "example"
}

POST /api/v1/support/tickets

POST

/api/v1/support/tickets

Create a support ticket

Parameters

Name	Type	Required	Description
subject	`string`	Required	Ticket subject line
body	`string`	Required	Initial message body (becomes first reply)
category_slug	`string`	Optional	category_slug
priority	`"low" \| "medium" \| "high" \| "urgent"`	Optional	TicketPriority
source	`"dashboard" \| "contact_form" \| "email" \| "discord" \| "api"`	Optional	TicketSource
ticket_metadata	`object`	Optional	ticket_metadata
attachments	`object[]`	Optional	attachments

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/support/tickets \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "example_subject",
    "body": "example_body"
  }'

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/support/tickets

GET

/api/v1/support/tickets

List own tickets

Parameters

Name	Type	Required	Description
status	`"open" \| "awaiting_reply" \| "in_progress" \| "resolved" \| "closed" \| "merged"`	Optional	status
priority	`"low" \| "medium" \| "high" \| "urgent"`	Optional	priority
category	`string`	Optional	Category slug
search	`string`	Optional	search
page	`integer`	Optional	pageDefault: `1`
page_size	`integer`	Optional	page_sizeDefault: `20`

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/support/tickets \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "tickets": [],
  "total": 0,
  "page": 0,
  "page_size": 0,
  "pages": 0,
  "filters": "example"
}

POST /api/v1/support/tickets/public

POST

/api/v1/support/tickets/public

Submit a contact form (unauthenticated)

Parameters

Name	Type	Required	Description
name	`string`	Required	Submitter display name
email	`string`	Required	Submitter email address
subject	`string`	Required	Ticket subject line (or contact form subject label)
message	`string`	Required	Message body (becomes first reply on the ticket)
category_slug	`string`	Optional	category_slug
website	`string`	Optional	Leave empty — anti-bot honeypot field

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/support/tickets/public \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "example_name",
    "email": "example_email",
    "subject": "example_subject",
    "message": "example_message"
  }'

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/support/tickets/{ticket_id}

GET

/api/v1/support/tickets/{ticket_id}

Get ticket detail

Parameters

Name	Type	Required	Description
ticket_id	`string`	Required	ticket_id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/support/tickets/<ticket_id> \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "id": "example",
  "ticket_ref": "example",
  "ticket_number": 0,
  "user_id": "example",
  "category_id": "example",
  "category": "example"
}

POST /api/v1/support/tickets/{ticket_id}/close

POST

/api/v1/support/tickets/{ticket_id}/close

Close own ticket

Parameters

Name	Type	Required	Description
ticket_id	`string`	Required	ticket_id

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/support/tickets/<ticket_id>/close \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "id": "example",
  "ticket_ref": "example",
  "ticket_number": 0,
  "user_id": "example",
  "category_id": "example",
  "category": "example"
}

DELETE /api/v1/support/tickets/{ticket_id}/gdpr

DELETE

/api/v1/support/tickets/{ticket_id}/gdpr

Delete a ticket and all associated data (GDPR erasure request)

Parameters

Name	Type	Required	Description
ticket_id	`string`	Required	ticket_id

Request Example

Bash

curl -X DELETE https://api.alterlab.io/api/v1/support/tickets/<ticket_id>/gdpr \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "ticket_id": "example",
  "ticket_ref": "example",
  "deleted": true,
  "message": "example"
}

PATCH /api/v1/support/tickets/{ticket_id}/mute

PATCH

/api/v1/support/tickets/{ticket_id}/mute

Mute or unmute ticket notifications

Parameters

Name	Type	Required	Description
ticket_id	`string`	Required	ticket_id
muted	`boolean`	Required	True to mute this ticket (suppress email notifications), False to unmute

Request Example

Bash

curl -X PATCH https://api.alterlab.io/api/v1/support/tickets/<ticket_id>/mute \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "muted": false
  }'

Response Example

JSON

{
  "ticket_id": "example",
  "is_muted": true,
  "message": "example"
}

POST /api/v1/support/tickets/{ticket_id}/reopen

POST

/api/v1/support/tickets/{ticket_id}/reopen

Reopen own ticket

Parameters

Name	Type	Required	Description
ticket_id	`string`	Required	ticket_id

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/support/tickets/<ticket_id>/reopen \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "id": "example",
  "ticket_ref": "example",
  "ticket_number": 0,
  "user_id": "example",
  "category_id": "example",
  "category": "example"
}

POST /api/v1/support/tickets/{ticket_id}/replies

POST

/api/v1/support/tickets/{ticket_id}/replies

Add reply to ticket

Parameters

Name	Type	Required	Description
ticket_id	`string`	Required	ticket_id
body	`string`	Required	Reply body (plain text or markdown)
is_internal_note	`boolean`	Optional	If True, the reply is only visible to admins (admin only)Default: `False`
attachments	`object[]`	Optional	attachments

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/support/tickets/<ticket_id>/replies \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "example_body",
    "is_internal_note": false
  }'

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/support/tickets/{ticket_id}/replies

GET

/api/v1/support/tickets/{ticket_id}/replies

List ticket replies

Parameters

Name	Type	Required	Description
ticket_id	`string`	Required	ticket_id
page	`integer`	Optional	pageDefault: `1`
page_size	`integer`	Optional	page_sizeDefault: `50`

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/support/tickets/<ticket_id>/replies \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "replies": [],
  "total": 0,
  "page": 0,
  "page_size": 0,
  "pages": 0
}

POST /api/v1/support/tickets/{ticket_id}/satisfaction

POST

/api/v1/support/tickets/{ticket_id}/satisfaction

Rate resolved ticket

Parameters

Name	Type	Required	Description
ticket_id	`string`	Required	ticket_id
rating	`integer`	Required	Satisfaction rating from 1 (very dissatisfied) to 5 (very satisfied)
comment	`string`	Optional	comment

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/support/tickets/<ticket_id>/satisfaction \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rating": 0
  }'

Response Example

JSON

{
  "id": "example",
  "ticket_ref": "example",
  "ticket_number": 0,
  "user_id": "example",
  "category_id": "example",
  "category": "example"
}

POST /api/v1/support/upload

POST

/api/v1/support/upload

Upload a file attachment

Parameters

Name	Type	Required	Description
ticket_id	`string`	Optional	ticket_id

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/support/upload \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

POST /api/v1/unsubscribe

POST

/api/v1/unsubscribe

Unsubscribe from lifecycle emails

Parameters

Name	Type	Required	Description
uid	`string`	Required	Uid
type	`string`	Required	Type
token	`string`	Required	Token

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/unsubscribe \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "uid": "example_uid",
    "type": "example_type",
    "token": "example_token"
  }'

Response Example

JSON

{
  "ok": true,
  "message": "example"
}

GET /api/v1/usage/by-key

GET

/api/v1/usage/by-key

Get Usage By Key

Parameters

Name	Type	Required	Description
days	`integer`	Optional	Days of usage to queryDefault: `30`
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/usage/by-key \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "keys": [],
  "account_total_spend_microcents": 0,
  "account_total_requests": 0,
  "period_start": "example",
  "period_end": "example"
}

GET /api/v1/usage/estimate

GET

/api/v1/usage/estimate

Get Usage Estimate

Parameters

Name	Type	Required	Description
window_days	`integer`	Optional	Rolling window in days (1-30)Default: `7`
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/usage/estimate \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "avg_cost_per_request": "example",
  "total_cost_microcents": 0,
  "request_count": 0,
  "window_days": 0,
  "has_enough_data": true,
  "balance_microcents": 0
}

Last updated: March 2026