Skip to Content
For AI & agentsREST APIOpenAPI specification

OpenAPI specification

The StyleRef REST API publishes an OpenAPI 3.1 contract. It’s the machine-readable source of truth — custom GPTs, Zapier/Make, and OpenAPI-native agent frameworks consume it to use StyleRef without the MCP server.

The document

https://styleref.io/api/v1/openapi.json

Fetch it directly:

curl "https://styleref.io/api/v1/openapi.json"

The JSON is canonical. Where this documentation and the spec differ, the spec wins — it ships with the API and is maintained in lockstep with the route handlers.

What it describes

  • Servers — the base URL https://styleref.io/api/v1.
  • Paths — GET /styles, GET /styles/{ref}, GET /styles/{ref}/style.md, POST /styles/{ref}/save, POST /style-md/validate, POST /extractions, GET /extractions/{id}, GET /me/styles, GET /me/saved-styles, GET /me/extractions, and GET /me/extractions/{id}.
  • Security — a bearerAuth scheme (a StyleRef OAuth token). Optional on the gallery reads, where scope styles:read additionally resolves your private styles; required on /extractions (scope extract), /styles/{ref}/save (scope styles:write), and every /me/* read (scope styles:read).
  • Schemas — SearchResults, StyleCard, LintResult, ExtractionStarted, ExtractionStatus, ExtractionHistory, ExtractionHistoryEntry, MyStyles, and Error.
  • Responses — the shared error envelopes, including NotGenerated (HTTP 409, styleref_not_generated) and PlanLimited (HTTP 403).
  • Request bodies — including the multipart/form-data upload for POST /extractions, described with format: binary.

Using it

  • Custom GPT / Action — import the URL as an Action; the model calls the endpoints from the schema.
  • OpenAPI clients — generate a typed client from the document.
  • Automation platforms — point Zapier/Make at the endpoints described in the spec.

The contract changes additively — agents cache specs — so existing integrations keep working across updates.

Next steps

Last updated on
Endpoints referenceCLI (npx styleref)