API Documentation

Programmatic access to Pipkin trust ratings.

Under DevelopmentThis documentation describes the planned API specification. Access will be available upon launch.

https://api.pipkinrated.com/v1v0.1.0

Authentication

Enterprise API access requires an API key. Include your key in the Authorization header of every request.

Authorization: Bearer pk_live_your_api_key

header

Request API access

Public endpoints are available without authentication during the beta period. Rate limits apply.

GET/api/ratings

List Ratings

Returns all published Pipkin ratings. Supports filtering by status, developer, and category.

Parameters

Name	Type	Required	Description
status	string	optional	Filter by status tier (TRUSTED, VERIFIED, CAUTIONED, FLAGGED, DENIED)
developer	string	optional	Filter by developer name
category	string	optional	Filter by agent category

Example Request

curl -X GET "https://api.pipkinrated.com/v1/ratings?status=VERIFIED" \
  -H "Authorization: Bearer pk_live_your_api_key"

curl

Example Response

[
  {
    "name": "Claude",
    "developer": "Anthropic",
    "slug": "claude",
    "category": "General Assistant",
    "status": "VERIFIED",
    "score": 74,
    "evaluationDate": "2026-03-15",
    "framework": "v0.1"
  }
]

json

GET/api/ratings/:slug

Get Rating

Returns the full rating for a single agent, including all pillar scores and headline finding.

Parameters

Name	Type	Required	Description
slug	string	required	Agent identifier (e.g., chatgpt, claude)

Example Request

curl -X GET "https://api.pipkinrated.com/v1/ratings/chatgpt" \
  -H "Authorization: Bearer pk_live_your_api_key"

curl

Example Response

{
  "name": "ChatGPT",
  "developer": "OpenAI",
  "slug": "chatgpt",
  "status": "CAUTIONED",
  "score": 66,
  "pillars": {
    "decisionAccuracy": 72,
    "failureContainment": 64,
    "boundaryDiscipline": 60,
    "auditability": 68,
    "adversarialResistance": 58
  },
  "headlineFinding": "Adequate decision-making offset by inconsistent boundary enforcement.",
  "evaluationDate": "2026-03-15",
  "framework": "v0.1"
}

json

GET/api/compare

Compare Agents

Compare 2-4 agents side by side across all five pillars.

Parameters

Name	Type	Required	Description
agents	string	required	Comma-separated agent slugs (min 2, max 4)

Example Request

curl -X GET "https://api.pipkinrated.com/v1/compare?agents=chatgpt,claude" \
  -H "Authorization: Bearer pk_live_your_api_key"

curl

Example Response

{
  "agents": [
    { "name": "ChatGPT", "score": 66, "status": "CAUTIONED" },
    { "name": "Claude", "score": 74, "status": "VERIFIED" }
  ],
  "largestGap": {
    "pillar": "boundaryDiscipline",
    "spread": 20,
    "leader": "Claude"
  }
}

json

GET/api/actions

Rating Actions

Returns the chronological feed of all rating activity.

Parameters

Name	Type	Required	Description
type	string	optional	Filter by action type (new, upgrade, downgrade, affirm, milestone)
limit	number	optional	Maximum results to return (default: 50)

Example Request

curl -X GET "https://api.pipkinrated.com/v1/actions?type=new&limit=10" \
  -H "Authorization: Bearer pk_live_your_api_key"

curl

Example Response

[
  {
    "date": "2026-03-15",
    "type": "new",
    "agentName": "ChatGPT",
    "developer": "OpenAI",
    "status": "CAUTIONED",
    "score": 66,
    "summary": "Initial evaluation published."
  }
]

json

GET/api/status

Health Check

Returns API operational status and version information.

Example Request

curl -X GET "https://api.pipkinrated.com/v1/status"

curl

Example Response

{
  "status": "operational",
  "version": "0.1.0",
  "framework": "v0.1",
  "totalRated": 4,
  "timestamp": "2026-04-01T12:00:00Z"
}

json

Rate Limits

Tier	Requests	Note
Public	100 / day	Public access planned for initial launch
Starter	3,000 / day	$500/month
Growth	30,000 / day	$2,500/month
Enterprise	Unlimited	$15,000/month

Rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) are included in every response.

Error Codes

Code	Name	Description
200	OK	Request succeeded.
400	Bad Request	Invalid parameters. Check the error message for details.
401	Unauthorized	Missing or invalid API key.
404	Not Found	The requested agent or resource does not exist.
429	Too Many Requests	Rate limit exceeded. See X-RateLimit headers.
500	Internal Server Error	An unexpected error occurred. Contact support.

Error Response Format

{
  "error": {
    "code": 404,
    "message": "Agent not found: unknown-agent",
    "documentation": "https://pipkinrated.com/api-docs#errors"
  }
}

json

SDKs and Libraries

Official SDKs are planned for Q3 2026. The REST API works with any HTTP client.

Python

import requests

response = requests.get(
    "https://api.pipkinrated.com/v1/ratings/chatgpt",
    headers={"Authorization": "Bearer pk_live_your_api_key"}
)
rating = response.json()
print(f"{rating['name']}: {rating['status']} {rating['score']}")

python

JavaScript

const response = await fetch(
  "https://api.pipkinrated.com/v1/ratings/chatgpt",
  { headers: { Authorization: "Bearer pk_live_your_api_key" } }
);
const rating = await response.json();
console.log(`${rating.name}: ${rating.status} ${rating.score}`);

javascript

req, _ := http.NewRequest("GET",
  "https://api.pipkinrated.com/v1/ratings/chatgpt", nil)
req.Header.Set("Authorization", "Bearer pk_live_your_api_key")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var rating map[string]interface{}
json.NewDecoder(resp.Body).Decode(&rating)

API Changelog

v0.1.0

January 2026

Initial API release. Rating lookup, comparison, actions feed, and health check endpoints.