API - Cooperative Computing Alliance

The admin API gives you programmatic access to manage brands, tags, verified domains, IP prefixes, verified ASNs, and system statistics. You can use it to automate data management tasks or integrate with other tools.

Authentication#

All admin API requests require a valid Cloudflare Access token. The token is passed through Cloudflare Access headers after you authenticate through the identity provider. Requests without a valid token receive a 403 Forbidden response.

Conventions#

All request and response bodies use JSON.
Successful responses return 200 (for reads and updates) or 201 (for creates).
Error responses include an error field with a human-readable description.
Timestamps are in ISO 8601 format.
List endpoints support pagination with page and limit query parameters.
PUT and PATCH both work for updates.

Brands#

List all brands#

GET /api/v1/brands

Returns an array of all brands.

Get a single brand#

GET /api/v1/brands/:id

Returns one brand by its ID.

Get brand dependencies#

GET /api/v1/brands/:id/dependencies

Returns counts of everything linked to this brand: tags, verified domains, IP prefixes, and verified ASNs. Check this before deleting a brand.

Create a brand#

POST /api/v1/brands

Field	Type	Required	Description
brandId	string	Yes	A unique short identifier (for example, google). Cannot be changed later.
name	string	Yes	The display name shown in badges.
color	string	No	A hex color code for the badge background (for example, #4285F4).
url	string	No	A link to the brand's website.
location	string	No	The brand's headquarters or primary location.

Bulk create brands#

POST /api/v1/brands?action=bulk

Send an array of brand objects. Each object uses the same fields as single creation.

Update a brand#

PUT /api/v1/brands/:id

Send only the fields you want to change. You cannot change the brandId.

Delete a brand#

DELETE /api/v1/brands/:id

Check dependencies first. Deleting a brand may affect associated tags, domains, and prefixes.

TXT record tags#

List all TXT tags#

GET /api/v1/txt-tags

Get a single TXT tag#

GET /api/v1/txt-tags/:id

Create a TXT tag#

POST /api/v1/txt-tags

Field	Type	Required	Description
pattern	string	Yes	The text pattern to match against TXT records. Must be unique.
brandId	string	No	The brand this tag belongs to.
serviceName	string	No	A custom name for the badge (defaults to the brand name).
color	string	No	Overrides the brand's default badge color.
url	string	No	A clickable link on the badge.

Bulk create TXT tags#

POST /api/v1/txt-tags?action=bulk

Send an array of tag objects.

Update a TXT tag#

PUT /api/v1/txt-tags/:id

Delete a TXT tag#

DELETE /api/v1/txt-tags/:id

MX record tags#

Uses the same endpoint structure and fields as TXT tags, at /api/v1/mx-tags.

Endpoint	Method
/api/v1/mx-tags	GET (list), POST (create)
/api/v1/mx-tags/:id	GET (read), PUT (update), DELETE (delete)

Request body fields are the same as TXT tags. The pattern field is matched against MX record hostnames using suffix matching.

NS record tags#

Uses the same endpoint structure and fields as TXT tags, at /api/v1/ns-tags.

Endpoint	Method
/api/v1/ns-tags	GET (list), POST (create)
/api/v1/ns-tags/:id	GET (read), PUT (update), DELETE (delete)

Request body fields are the same as TXT tags. The pattern field is matched against nameserver hostnames using suffix matching.

Verified domains#

List all verified domains#

GET /api/v1/verified-domains

Get a single verified domain#

GET /api/v1/verified-domains/:id

Create a verified domain#

POST /api/v1/verified-domains

Field	Type	Required	Description
apexDomain	string	Yes	The registered domain (for example, google.com). Must be unique.
brandId	string	Yes	The brand this domain belongs to.
secondaryLine	string	No	Extra context shown below the brand name.
tertiaryLine	string	No	A third line of context.
subdomainTreatment	string	No	How subdomains are handled: noSubdomains (default), allSubdomains, or pattern.
verificationType	string	No	How ownership was confirmed (for example, manual, dns).

Update a verified domain#

PUT /api/v1/verified-domains/:id

Delete a verified domain#

DELETE /api/v1/verified-domains/:id

IP prefixes#

List all IP prefixes#

GET /api/v1/ip-prefixes

Get a single IP prefix#

GET /api/v1/ip-prefixes/:id

Create an IP prefix#

POST /api/v1/ip-prefixes

Field	Type	Required	Description
ipPrefix	string	Yes	The IP range in CIDR notation (for example, 8.8.8.0/24). Must be unique.
ipVersion	integer	Yes	4 for IPv4, 6 for IPv6.
brandId	string	Yes	The brand that owns this IP range.
description	string	No	A note about what this prefix is used for.

Update an IP prefix#

PUT /api/v1/ip-prefixes/:id

Delete an IP prefix#

DELETE /api/v1/ip-prefixes/:id

Statistics#

Overview#

GET /api/v1/stats/overview

Returns counts for all main data types: brands, tags, verified domains, IP prefixes, and verified ASNs.

Data integrity#

GET /api/v1/stats/integrity

Returns results of the latest data integrity check, including foreign key validation and orphaned record detection.

Recent changes#

GET /api/v1/stats/recent-changes?limit=20

Returns the most recent changes across all data types. The limit parameter controls how many results to return (default: 20).

Search#

Global search#

GET /api/v1/search?q=query

Searches across all entity types (brands, tags, domains, prefixes) for records matching the query string.

Brand search#

GET /api/v1/search-brands?q=query

Searches brands by name or ID.

Change history#

List recent history#

GET /api/v1/history

Returns revision history entries across all data types.

Get a specific history entry#

GET /api/v1/history/:id

Audit logs#

List audit log entries#

GET /api/v1/audit-logs

Returns audit log entries. Supports filters for user, action type, entity type, and date range.

Get a specific audit entry#

GET /api/v1/audit-logs/:id

Data management#

Export#

GET /api/v1/export?type=all

Exports system data as JSON. The type parameter can be all, brands, txt-tags, mx-tags, ns-tags, or verified-domains.

Import#

POST /api/v1/import

Imports previously exported JSON data. Uses "insert or ignore" — existing records are not overwritten.

Scan management#

Trigger a scan#

POST /api/admin/scans/trigger

Manually triggers a scheduled scan. Send the scheduledScanId in the request body, or omit it to trigger all active scans.

Activate scheduled scans#

POST /api/admin/scans/activate

Activates scheduled scans by setting the next run time and enabling the active flag.

Test a single domain scan#

GET /api/admin/test-scan?domain=example.com&profile=standard

Runs a one-off scan of a single domain for testing. Returns the analysis results.

Health check#

GET /health

Returns the service health status. No authentication required.

Public API#

The public website provides a JSON endpoint that anyone can use without authentication:

Domain lookup#

GET /raw/{domain}

Returns a JSON object with the domain's current DNS records, security status (DNSSEC, SPF, DMARC, DKIM, HSTS, HSTS Preload, MTA-STS, TLS-RPT), WHOIS data, and identified services.

This endpoint returns the current, real-time state of the domain. It does not include historical analysis data, change history, or security scores — those are only available through the admin interface.

Error responses#

All errors follow this format:

{
  "error": "A description of what went wrong",
  "status": 400
}

Code	What it means
400	Bad request — a required field is missing or a value is invalid.
403	Forbidden — you are not authenticated, or you don't have permission.
404	Not found — the item you requested doesn't exist.
409	Conflict — a record with the same unique field already exists.
500	Server error — something went wrong on the server side.