{"slug":"oip-rest","title":"OIP REST Protocol","body":"OIP (Object Invocation Protocol) defines a protocol for object invocation.\nOIP uses REST (Representational State Transfer) principles for resource interaction.\nEvery OIP action is an invocation, performed via a defined route.\nEvery invocation appends to an immutable ledger, producing a receipt.\nThe receipt provides cryptographic proof of the invocation and its outcome.\n\n## Introduction\n\nOIP (Object Invocation Protocol) defines a protocol for invoking work objects. An OIP work object is a unit of computation that performs a specific task. OIP ensures every invocation appends to an immutable ledger and produces a receipt, enabling replay and repair.\n\nREST (Representational State Transfer) is an architectural style for distributed hypermedia systems. REST defines a set of constraints for designing Application Programming Interfaces (APIs). An API is a set of defined rules enabling different applications to communicate with each other. REST interactions involve stateless requests and standard HTTP methods operating on resources identified by Uniform Resource Locators (URLs).\n\nMCP (Model Context Protocol) is an open standard where an AI model connects to an MCP server over a session. The MCP server exposes tools, resources, and prompts the model can call. MCP establishes a persistent session for contextual interactions. REST operates with stateless requests, contrasting with MCP's session-based model.\n\nJSON (JavaScript Object Notation) is a lightweight data-interchange format. OIP uses JSON for defining object schemas and data payloads.\n\nCLI (Command-Line Interface) refers to a text-based interface for interacting with a computer program. CLI tools perform OIP invocations.\n\n## OIP REST Mechanisms\n\nOIP implements REST principles for object invocation and resource management. The OIP unit is the work object. An OIP invocation is a request to a work object to perform a defined action. The `/api/dispatch` route performs object invocations. A `POST` request to `/api/dispatch` with a `key` and `body` invokes an object. A `GET` request to `/api/dispatch` with `invoke=KEY` and `body` parameters also invokes an object. Every invocation appends to an immutable ledger. The OIP proof is the receipt. A receipt is returned at `/api/dispatch?receipt=inv_ID` upon successful ledger append. The OIP loop defines the lifecycle of an invocation: object, invoke, ledger, receipt, replay, repair.\n\nOIP uses standard HTTP methods: `GET` retrieves resource state. `POST` creates a new resource or performs an action. `PATCH` applies partial modifications to a resource. `PUT` replaces a resource. `DELETE` removes a resource. The URL identifies the target object or resource. The request body carries the input parameters for the invocation.\n\n## Machine Shape\n\nAn OIP REST action is machine-native when it defines the following properties:\n\n```json\n{\n  \"action_properties\": {\n    \"method\": { \"type\": \"string\", \"description\": \"The HTTP method (e.g., GET, POST).\" },\n    \"url\": { \"type\": \"string\", \"description\": \"The Uniform Resource Locator (URL) for the action.\" },\n    \"body_schema\": { \"type\": \"object\", \"description\": \"A JSON schema for the request body.\" },\n    \"auth\": { \"type\": \"object\", \"description\": \"Authentication requirements for the action.\" },\n    \"success_shape\": { \"type\": \"object\", \"description\": \"A JSON schema for a successful response.\" },\n    \"failure_shape\": { \"type\": \"object\", \"description\": \"A JSON schema for an error response.\" },\n    \"proof_route\": { \"type\": \"string\", \"description\": \"The URL route for retrieving the invocation receipt.\" }\n  },\n  \"routes\": {\n    \"/api/dispatch\": {\n      \"description\": \"The primary OIP endpoint for invoking work objects. Accepts object key and body.\",\n      \"methods\": {\n        \"POST\": {\n          \"body_schema\": {\n            \"type\": \"object\",\n            \"properties\": {\n              \"key\": { \"type\": \"string\", \"description\": \"The unique identifier for the work object to invoke.\" },\n              \"body\": { \"type\": \"object\", \"description\": \"The input parameters for the object invocation.\" }\n            },\n            \"required\": [\"key\", \"body\"]\n          },\n          \"proof_route\": \"/api/dispatch?receipt={inv_ID}\"\n        },\n        \"GET\": {\n          \"query_params\": {\n            \"invoke\": { \"type\": \"string\", \"description\": \"The unique identifier for the work object to invoke.\" },\n            \"body\": { \"type\": \"string\", \"description\": \"JSON string of input parameters for the object invocation.\" }\n          },\n          \"proof_route\": \"/api/dispatch?receipt={inv_ID}\"\n        }\n      }\n    },\n    \"/api/articles\": {\n      \"description\": \"Endpoint for managing OIP documentation articles. Supports creation.\",\n      \"methods\": {\n        \"POST\": {\n          \"body_schema\": {\n            \"type\": \"object\",\n            \"properties\": {\n              \"title\": { \"type\": \"string\", \"description\": \"The title of the new article.\" },\n              \"body\": { \"type\": \"string\", \"description\": \"The markdown content of the new article.\" }\n            },\n            \"required\": [\"title\", \"body\"]\n          },\n          \"proof_route\": \"/api/dispatch?receipt={inv_ID}\"\n        }\n      }\n    },\n    \"/a/{slug}\": {\n      \"description\": \"Endpoint for retrieving a specific OIP documentation article by its slug.\",\n      \"methods\": {\n        \"GET\": {\n          \"params\": {\n            \"slug\": { \"type\": \"string\", \"description\": \"The unique identifier (slug) of the article.\" }\n          }\n        }\n      }\n    },\n    \"/a/mcp\": {\n      \"description\": \"Reference URL for the Model Context Protocol (MCP) documentation article.\",\n      \"methods\": {\n        \"GET\": {}\n      }\n    }\n  }\n}\n```\n\n## Example Use Case\n\nTo create a new article, an OIP client performs a `POST` invocation to the `/api/articles` route. The request body provides the article `title` and `body` as JSON. This invocation appends to the ledger and returns a receipt. A CLI tool performs this action with the following command:\n\n```bash\ncurl -X POST /api/articles \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"title\":\"OIP REST Example Article\",\"body\":\"This article demonstrates OIP REST principles.\"}'\n```\n\nThe server returns a receipt identifier, `inv_ID`, which proves the article creation invocation. The receipt is retrievable at `/api/dispatch?receipt=inv_ID`.\n\n## Receipt Rule\n\nAn OIP receipt proves the successful invocation of a work object via a defined route. The receipt contains the invocation ID, the invoked object's key, the input parameters, the timestamp, and a cryptographic signature. The receipt confirms the invocation's append to the immutable ledger.\n\n## Conformance Rule\n\nAn OIP implementation conforms to the REST protocol specification when it processes invocations via defined REST routes, appends every invocation to an immutable ledger, and returns a verifiable receipt at `/api/dispatch?receipt=inv_ID` for each successful invocation. Conformant behavior includes adherence to specified HTTP methods, URL structures, and JSON schemas for requests and responses.\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 03:02 · 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; API; CLI\n- 2026-07-02 23:37 · 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; API; CLI\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-rest","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-03T01:32:06-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-03T01:32:06-07:00"}