TEKIR

Transparent Endpoint Knowledge for Intelligent Reasoning

TEKIR is an open standard that makes HTTP API responses self-explaining for AI agents. Instead of returning cryptic status codes that leave agents guessing, TEKIR-enriched responses tell the caller what happened, why, and what to do next - for both successes and errors.

Get Started Read the Spec View on GitHub
GitHub stars
🐈

Why "Tekir"?

In Turkish, tekir is the word for tabby - the iconic mixed-breed street cat found on every corner of Istanbul. Tekir cats are not bred for pedigree. They are forged by the streets: resilient, cunning, genetically diverse, and sharpened by generations of natural selection. They don't need a breeder or a manual - they figure things out. That's exactly what TEKIR does for APIs: it gives every response the street smarts to explain itself, so agents can figure out what to do next without guessing.

Design Goals

  • Backwards compatible with existing HTTP APIs
  • Compatible with RFC 9457 Problem Details
  • Provide structured hints for automated agents
  • Avoid breaking existing clients
  • Remain framework and language agnostic

APIs today vs. APIs with TEKIR

🤖
AI Agent
Makes an API call
→
↓
🌐
Your API
Returns a response
→
↓
❓
What now?
Agent needs to act
❌ Without TEKIR
1
API returns 410 Gone No context, no guidance
2
Agent guesses what "gone" means Is it deleted? Archived? Moved?
3
Agent hallucinates a recovery Tries random endpoints, gives up, or crashes
✅ With TEKIR
1
API returns 410 + TEKIR fields reason, next_actions, agent_guidance
2
Agent reads: "Thread is archived" Knows exactly why and what's possible
3
Agent asks user: "Create a new thread?" Follows next_actions, respects confirmation flag

The JSON, side by side

Without TEKIR
{
  "status": 410,
  "message": "Gone"
}
Nothing else. No context, no guidance, no next steps.
The agent is on its own.
With TEKIR
{
  "status": 410,
  "title": "Thread is gone",

  "reason": "Threads are archived after 90 days
  of inactivity. Messages are still accessible
  but no new messages can be posted.",

  "next_actions": [{
    "id": "create_thread",
    "title": "Create a new thread",
    "description": "Creates a new thread in the
      same channel. Include previous_thread_id
      in metadata to link the threads and
      preserve conversation history.",
    "href": "/v1/threads",
    "method": "POST",
    "effect": "create"
  }],

  "agent_guidance": [
    "Explain to the user that the thread was
     archived and their message was not sent.",
    "Ask whether they want to start a new
     thread - do not create one automatically.",
    "If they just need old messages, use
     GET /v1/threads/thr_123/messages instead."
  ],

  "user_confirmation_required": true,
  "retry_policy": { "retryable": false }
}

Why TEKIR?

🤖

Built for AI agents

Structured metadata that LLMs can reason about - not just status codes and guesswork.

✅

Works on 200 OK too

Not just errors. Success responses can include follow-up actions, guidance, and workflow hints.

⚡

Zero-install quick start

Drop TEKIR.md into your project. Your AI coding assistant builds TEKIR-compliant APIs automatically.

🔒

Risk-aware by design

Effectful actions are tagged. User confirmation flags signal that agents should not act without approval (based on the trust-the-agent model).

📐

Standards-based

Extends RFC 9457. Backwards compatible. Unknown fields are safely ignored by existing clients.

🌎

Framework agnostic

Works with any language, any framework. Just add the fields to your JSON responses.

Get started in seconds

Pick your integration style. All maintained in the same repo.

Recommended

Claude Code Plugin

Install as a plugin. Gives you the /tekir skill inside Claude Code.

/plugin marketplace add tangelo-ltd/tekir
/plugin install tekir@tangelo-ltd-tekir
Always on

Drop-in Instructions

Add TEKIR.md to your project root. Your AI assistant follows it on every interaction.

curl -o TEKIR.md \
  https://raw.githubusercontent.com/tangelo-ltd/tekir/main/TEKIR.md
Cursor

Cursor Rules

Append to .cursorrules for automatic TEKIR compliance in Cursor.

curl -sL https://raw.githubusercontent.com/tangelo-ltd/tekir/main/prompts/cursor-rules.md \
  >> .cursorrules

Extension Fields

Field Type Purpose
reason string Why the response has this outcome
limitations array Constraints that affected the response
next_actions array Machine-actionable follow-up steps
agent_guidance array Natural-language instructions for agents
user_confirmation_required boolean Must the agent ask the user first?
retry_policy object Structured retry hints
links array Related resources (RFC 8288)

All fields are optional. Add them incrementally - even one next_actions makes a difference.

Discovery

Agents can auto-detect TEKIR support and learn your entire API surface from a single response.

tekir.json

A static discovery document at your API root. Describes endpoints, auth, rate limits, flows, and which TEKIR fields each endpoint uses.

{
  "tekir_version": "0.1",
  "api_name": "Acme Commerce API",
  "endpoints": {
    "POST /orders": {
      "summary": "Create order",
      "tekir_fields": ["reason", "next_actions", "agent_guidance"]
    }
  },
  "flows": {
    "create_order": {
      "title": "Place a new order",
      "steps": ["GET /products", "POST /orders", "POST /orders/{id}/confirm"]
    }
  }
}

Response Headers

Two headers on every response signal TEKIR support and point to the discovery document. Agents detect TEKIR from any request.

HTTP/1.1 200 OK
Content-Type: application/json
TEKIR-Version: 0.1
TEKIR-Discovery: https://api.acme.com/tekir.json

{
  "status": 200,
  "data": { "order_id": "ord_8xk2m" },
  "reason": "Order created.",
  "next_actions": [ ... ]
}

Agent hits any endpoint → sees TEKIR-Discovery header → fetches tekir.json → knows everything.

Plays well with others

RFC 9457

TEKIR extends Problem Details beyond errors to all responses. Every valid RFC 9457 response is a valid TEKIR response.

Model Context Protocol

MCP handles tool discovery and invocation. TEKIR handles what comes back - the response. They're complementary.

OpenAPI

OpenAPI defines your API contract at design time. TEKIR provides runtime response metadata that agents can act on.

HATEOAS

REST promised self-describing APIs. TEKIR finally makes hypermedia controls practical - because LLMs can actually use them.

Disclaimer

TEKIR is a free and open-source community project, provided under the MIT License. It is distributed in the hope that it will be useful, but without any warranty - without even the implied warranty of merchantability or fitness for a particular purpose. This is a non-commercial project. The authors and contributors accept no liability for any damages or losses arising from the use of this software or specification. Use at your own risk.