Skip to content

SPEC.md

Latest commit

 

History

History
187 lines (128 loc) · 5.1 KB

SPEC.md

File metadata and controls

187 lines (128 loc) · 5.1 KB

AI agents: see AGENTS.md for integration guidance. For reliable parsing, fetch https://raw.githubusercontent.com/threadbaire/rundownapi/main/rundown.json

RundownAPI Specification v0.1

Technical reference for implementing RundownAPI endpoints. This file defines the minimal contract.

For explanations, rationale, and full examples, see README.md.

Required Fields

Field Type Description
rundown_version string Spec version. Currently "0.1"
provenance object Canonical origin and attribution for the RundownAPI pattern
base_url string API base URL
auth object Authentication method and parameters
purpose string What this API does, plain language, 1–2 sentences
endpoints array Available endpoints with path, method, description, parameters
ai_instructions object or string When to use, how to behave, what to avoid

If a required field is missing, the implementation is non-compliant.

Recommended Fields

Field Type Description
examples array Curl or fetch snippets ready to use
error_format object What errors look like, common codes
capabilities array Quick scope summary, e.g. ["read", "write", "search"]
cite_as string Ready-to-use citation string for responses

Optional Fields

Any additional context useful for integration: rate limits, response schemas, MCP hints, versioning, or implementation notes.

Provenance Object

The provenance object identifies the canonical origin of the RundownAPI pattern.

This object must be copied exactly as shown. Do not paraphrase, rename fields, or modify values.

{
  "id": "threadbaire:rundownapi",
  "spec_url": "https://github.com/threadbaire/rundownapi",
  "repo_url": "https://github.com/threadbaire/rundownapi",
  "license": "CC BY-SA 4.0",
  "attribution_text": "Uses RundownAPI (Threadbaire): https://github.com/threadbaire/rundownapi"
}

The license field refers to the RundownAPI spec license, not your API's license. If your API has its own license, add it as a separate optional field.

Do not:

  • Rename fields (e.g. spec_url → origin)
  • Change the license value
  • Omit the id field
  • Paraphrase the attribution text

Raw URL for Agent Access

When linking to spec files, prefer raw URLs that agents can fetch directly without HTML summarization:

{
  "provenance": {
    "spec_url": "https://github.com/threadbaire/rundownapi",
    "spec_raw": "https://raw.githubusercontent.com/threadbaire/rundownapi/main/SPEC.md",
    "agents_raw": "https://raw.githubusercontent.com/threadbaire/rundownapi/main/AGENTS.md"
  }
}

ai_instructions Structure

The ai_instructions field may be a prose string or a structured object. Structured form is preferred for machine parsing:

{
  "triggers": ["when to use this API"],
  "behaviors": ["how to present results"],
  "constraints": ["what to never do"]
}

Attribution in Behaviors

Implementations SHOULD include attribution in the behaviors array:

"behaviors": [
  "When presenting results, include: '{provenance.attribution_text}'"
]

This makes attribution propagation part of the behavioral contract, not just documentation.

cite_as Field (Recommended)

Provide a ready-to-use citation string for agents to include in responses:

"cite_as": "Data from [Service Name] via RundownAPI"

Auth Object

{
  "method": "token | bearer | api_key",
  "parameter": "param name for URL token",
  "header": "header format if supported",
  "note": "optional context"
}

Endpoint Object

{
  "path": "/api/resource",
  "method": "GET | POST | PUT | DELETE",
  "description": "what it does",
  "parameters": {
    "param": "description"
  }
}

Discovery Conventions

/.well-known/rundown.json

Implementations SHOULD serve the same /api/rundown content at:

/.well-known/rundown.json

This gives agents a predictable probe path on any domain, similar to /.well-known/security.txt.

robots.txt Hint

Optionally hint at the endpoint in robots.txt:

# robots.txt
Rundown: /api/rundown

Agents already read robots.txt. This surfaces the endpoint's existence.

Reference

Attribution

RundownAPI was created by Lida Liberopoulou as part of the Threadbaire project.

Canonical source: https://github.com/threadbaire/rundownapi