Protocol 80 — API Documentation

Infrastructure

Gemini API — Evaluation Engine

Supermemory — Context & Cache

DigitalOcean — Deployment

Agentic Readiness Score — Criteria

Each criterion is rated 0–10 by Gemini, then combined via weighted average into a final Agentic Readiness Score.

Semantic Clarity

Are endpoint names, fields, and enums self-describing for an LLM agent?

Weight: 25%

Type Accuracy

Are request/response schemas strict, typed, and unambiguous?

Weight: 25%

Token Efficiency

How many tokens does a typical request+response cost an agent?

Weight: 20%

Idempotency Safety

Does the API accept Idempotency-Key headers to prevent duplicate billing on retries?

Weight: 15%

Documentation Clarity

Can an agent parse the docs to self-integrate without human help?

Weight: 15%

Endpoints

POST /evaluate Create a new agentic readiness evaluation ▾

Submit an API endpoint (or OpenAPI spec URL) for agentic readiness analysis. The evaluation is processed asynchronously via Gemini — you receive an evaluation ID to poll for results.

Headers

Name	Type	Description
Content-Typerequired	string	application/json
Idempotency-Key	string	Unique key to prevent duplicate evaluations on agent retries. UUID v4 recommended.

Request Body

Field	Type	Description
urlrequired	string	The API base URL or OpenAPI/Swagger spec URL to evaluate.
method	string	HTTP method to test. Defaults to `GET`. Enum: GET, POST, PUT, PATCH, DELETE.
headers	object	Optional headers to include when probing the endpoint.
body	object \| null	Optional request body for POST/PUT/PATCH evaluations.
callback_url	string \| null	Webhook URL to receive results when evaluation completes.

Example Request

                     JSON
                     // POST /api/evaluate
                     {
                     "url": "https://api.example.com/v2/openapi.json",
                     "method": "POST",
                     "headers": {
                     "Authorization": "Bearer sk-test-..."
                     },
                     "body": null,
                     "callback_url": "https://hooks.example.com/p80"
                     }
                  

Responses

201

Evaluation created successfully.

                           {
                           "id": "eval_a1b2c3d4e5f6",
                           "status": "processing",
                           "created_at": "2026-02-28T14:30:00Z",
                           "estimated_seconds": 12
                           }
                        

409

Duplicate — an evaluation with this Idempotency-Key already exists. Returns the existing evaluation ID.

422

Validation error — invalid URL format or unsupported method.

500

Internal server error. Safe to retry with the same Idempotency-Key.

Try it

Idempotency-Key Request Body

201 Created 238ms

                           {
                           "id": "eval_f7g8h9i0j1k2",
                           "status": "processing",
                           "created_at": "2026-02-28T15:42:07Z",
                           "estimated_seconds": 10
                           }
                        

GET /evaluate/{id} Retrieve evaluation results ▾

Fetch the results of a previously submitted evaluation. While the evaluation is still processing, status will be "processing". Once complete, the full scoring breakdown and recommendations are returned.

Path Parameters

Name	Type	Description
idrequired	string	The evaluation ID returned from the POST request. Format: `eval_*`

Example Response — Completed

                     200 OK
                     {
                     "id": "eval_a1b2c3d4e5f6",
                     "status": "completed",
                     "url": "https://api.example.com/v2/openapi.json",
                     "agentic_readiness_score": 7.4,
                     "breakdown": {
                     "semantic_clarity": { "score": 8, "weight": 0.25 },
                     "type_accuracy": { "score": 9, "weight": 0.25 },
                     "token_efficiency": { "score": 6, "weight": 0.20 },
                     "idempotency_safety": { "score": 5, "weight": 0.15 },
                     "documentation_clarity": { "score": 8, "weight": 0.15 }
                     },
                     "token_usage": {
                     "request_tokens": 342,
                     "response_tokens": 1087,
                     "total": 1429
                     },
                     "recommendations": [
                     "Add Idempotency-Key support to POST endpoints",
                     "Reduce response payload — 40% of fields are unused by agents",
                     "Add enum descriptions to status fields"
                     ],
                     "evaluated_at": "2026-02-28T14:30:12Z"
                     }
                  

Example Response — Processing

                     200 OK
                     {
                     "id": "eval_a1b2c3d4e5f6",
                     "status": "processing",
                     "progress": 0.65,
                     "estimated_seconds_remaining": 4
                     }
                  

Responses

200

Evaluation found. Returns either processing status or completed results.

404

Evaluation ID not found.

Try it

Evaluation ID

200 OK 87ms

                           {
                           "id": "eval_a1b2c3d4e5f6",
                           "status": "completed",
                           "agentic_readiness_score": 7.4,
                           "breakdown": { /* ... */ },
                           "recommendations": [ /* ... */ ]
                           }
                        