{"slug":"oip-api","title":"What is an API?","body":"## What this article explains\n\nAn API (Application Programming Interface) is a set of rules for asking software to do something or return something. In the miscsubjects.com build, the API is not a vague integration idea. It is the exact HTTP (Hypertext Transfer Protocol) route, method, headers, body shape, and response shape for one object.\n\n## Plain words\n\nA person can click a page. A model or script usually calls an API. The API call says: here is the route, here is the object, here is the input, now return the result. A server is a computer that hosts software. A token is a secret code used for authentication. An endpoint is a specific URL (Uniform Resource Locator) that an API uses to interact with a server.\n\n## Introduction to MCP and OIP\n\nMCP (Model Context Protocol) is an open standard. An AI model connects to an MCP server over a session. The server exposes tools, resources, and prompts the model can call. MCP is not a content-management system. It provides a structured environment for AI models to operate within.\n\nOIP (Object Invocation Protocol) differs from MCP. OIP uses plain URLs and receipts. It has no persistent session. Any model that can open a URL can act using OIP.\n\nOIP uses a REST (Representational State Transfer) architecture. REST is an architectural style for designing networked applications. REST uses HTTP methods, such as GET and POST, to interact with resources. JSON (JavaScript Object Notation) is a lightweight data interchange format. It is used to exchange data between a server and a client.\n\n## How APIs work in OIP\n\nOIP treats every API route as an object boundary. A caller reads the route contract. It sends the required input. It receives a result. Then, it can check the ledger or receipt.\n\nA useful API article must say what the route does. It must state what input it accepts. It must show what comes back. It must explain how to prove it ran.\n\nFor example, to invoke an object, you can use the `/api/dispatch` route.\n*   Use a POST method. Send a JSON body with the `key` and `body` fields.\n*   You can also use a GET method. Pass the `invoke` and `body` parameters as query strings.\n\nEvery invocation lands in an append-only ledger. A receipt is issued.\n*   The receipt for an invocation can be retrieved using the `/api/dispatch` route. Use a GET method. Pass the `receipt` parameter.\n\nOther OIP routes allow reading content.\n*   To read an article by its slug, use the `/api/articles` route with a GET method. Pass the `slug` parameter.\n*   To directly access an article, use the `/a/<slug>` route.\n\n## Using curl with OIP\n\nYou can use curl to interact with the OIP API. Curl is a command-line tool. CLI (Command-Line Interface) refers to using text commands to interact with a computer program.\n\nHere are detailed curl examples for common OIP operations:\n\n**1. Invoke an object using POST:**\nThis sends a JSON payload to the `/api/dispatch` route.\n```bash\ncurl -X POST \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"key\":\"your_object_key\",\"body\":\"your_object_input\"}' \\\n  https://miscsubjects.com/api/dispatch\n```\n\n**2. Invoke an object using GET:**\nThis passes the object key and body as URL query parameters to the `/api/dispatch` route.\n```bash\ncurl 'https://miscsubjects.com/api/dispatch?invoke=your_object_key&body=your_object_input'\n```\n\n**3. Retrieve an invocation receipt:**\nAfter an invocation, you get an `inv_ID`. Use this ID to check the ledger.\n```bash\ncurl 'https://miscsubjects.com/api/dispatch?receipt=inv_ID_from_previous_invocation'\n```\n\n**4. Read an article using the API:**\nThis retrieves article data in JSON format.\n```bash\ncurl 'https://miscsubjects.com/api/articles?slug=oip-api'\n```\n\n**5. Read an article directly:**\nThis accesses the human-readable page for an article.\n```bash\ncurl 'https://miscsubjects.com/a/oip-api'\n```\n## Latest clarity reviews (live)\n\nFresh models are sent this article's bundle and asked two separate questions: how clear is the machine JSON, and how clear is the English body. Scores are 0 to 10. The full history is in the append-only ledger.\n\n- 2026-07-03 00:57 · model `@cf/meta/llama-3.3-70b-instruct-fp8-fast` · NEEDS WORK · JSON 9/10 · English 8/10 · zero-context human 6/10\n  - gaps named: MCP explanation; Detailed curl usage examples\n- 2026-07-02 23:35 · model `@cf/meta/llama-3.3-70b-instruct-fp8-fast` · NEEDS WORK · JSON 9/10 · English 8/10 · zero-context human 6/10\n  - gaps named: MCP explanation; Detailed curl usage examples\n\nHow the loop self-corrects: a failing review queues a model revision of this article (a new append-only version). A missing concept named by a reviewer queues a brand-new machine-written article, which then enters the same review cycle.","hero":null,"images":[],"style":{"accent":"#16324f","measure":860},"tags":["oip","object-invocation-protocol","protocol-specification","machine-native-json","primer"],"model":null,"ledger":null,"embeds":[],"widgets":[{"type":"stat","value":2,"label":"revision"},{"type":"note","title":"Zero-context rule","text":"A reader should understand the protocol unit, object contract, invocation route, receipt schema, and repair path from this page plus its machine bundle."},{"type":"note","title":"Machine-native rule","text":"The JSON is the executable map: object, routes, inputs, proof loop, ledger, and next article to open."}],"home":false,"claims":[{"id":"oip-c1","tier":"system","text":"The OIP article layer is generated from live directory rows, so it documents the objects that actually run the reference implementation.","who_claims":"system/oip_articles","source_ids":["oip-s3","oip-s4"]},{"id":"oip-c2","tier":"system","text":"The OIP operating path is caller to directory object to dispatch runner to invocation ledger to receipt.","who_claims":"system/oip_articles","source_ids":["oip-s1"]},{"id":"oip-c3","tier":"system","text":"Every executable capability in the reference implementation is reachable as an OIP object with a human article, a machine document, invocation history, and receipt path.","who_claims":"system/oip_articles","source_ids":["oip-s2","oip-s3"]},{"id":"oip-c4","tier":"system","text":"Tap & Go is the copy primitive: one drop carries credential, protocol, tree, search, execute, and receipt instructions without a separate token-map-bundle assembly step.","who_claims":"system/oip_articles","source_ids":["oip-s2"]},{"id":"oip-c5","tier":"system","text":"OIP receipts are the proof object for actions: they record request, response, actor, links, replay, repair, and lineage.","who_claims":"system/oip_articles","source_ids":["oip-s2","oip-s5"]}],"sources":[{"id":"oip-s1","type":"protocol","title":"BUILD_SPEC object invocation path","url":"https://miscsubjects.com/api/file/docs/BUILD_SPEC.md","summary":"Defines directory rows, dispatch, ledger, and the escalation path for changing the build.","quote":"Run anything: POST https://miscsubjects.com/api/dispatch {key, body}","claim_ids":["oip-c2"],"link_status":"ok","hash":"oipbuildspec0001"},{"id":"oip-s2","type":"protocol","title":"Object Invocation Protocol spec","url":"https://miscsubjects.com/api/file/docs/OIP.md","summary":"Defines OIP surfaces, invariant loop, receipt/replay/repair, and invocation envelopes.","quote":"identify, explain, invoke, ledger, yield","claim_ids":["oip-c3","oip-c4","oip-c5"],"link_status":"ok","hash":"oipspec00000002"},{"id":"oip-s3","type":"protocol","title":"Live OIP capability tree","url":"https://miscsubjects.com/api/dispatch?map=1&format=markdown","summary":"Public recursive capability tree.","quote":"root > shelf > system article > capability article > receipt","claim_ids":["oip-c1","oip-c3"],"link_status":"ok","hash":"oipmap0000000002"},{"id":"oip-s4","type":"protocol","title":"Directory row documentation","url":"https://miscsubjects.com/api/dispatch?key=OIP_TREE&format=markdown","summary":"Capability articles are generated from live rows.","quote":"Machine Contract","claim_ids":["oip-c1"],"link_status":"ok","hash":"oiprow0000000003"},{"id":"oip-s5","type":"protocol","title":"Invocation ledger","url":"https://miscsubjects.com/api/invocations","summary":"Append-only invocation records and receipt links.","quote":"invocations","claim_ids":["oip-c5"],"link_status":"ok","hash":"oipinvocations0005"}],"reviews":[],"extra":{"oip_virtual":true,"oip_type":"primer","count":2,"metric":"revision","primer":"oip-api","version":2,"author_model":"gemini/gemini-2.5-flash","revision_source":"revision"},"register":"oip_protocol","status":"published","revisions":0,"contributions":[],"provenance":[{"action":"generate","model":"system/oip_articles","ts":"2026-07-03T00:21:32-07:00","hash":"virtual-oip","tokens_in":0,"tokens_out":0}],"energy":{"passes":1,"tokens_in":0,"tokens_out":0,"tokens_total":0,"cost_usd":0,"models":{"system/oip_articles":1},"head":"virtual-oip"},"posted_at":"2026-07-02T00:00:00.000Z","created_at":"2026-07-02T00:00:00.000Z","updated_at":"2026-07-03T00:21:32-07:00"}