{"slug":"oip-curl","title":"How to operate the miscsubjects.com build with curl","body":"## How to operate the miscsubjects.com build with curl\n\n`curl` is a Command Line Interface (CLI) tool. It sends requests over the internet. You can use `curl` to interact with the `miscsubjects.com` build. This lets a human or an Artificial Intelligence (AI) model operate the build without a web browser. The build uses the Object Invocation Protocol (OIP). OIP is different from the Model Context Protocol (MCP).\n\n### OIP and MCP\n\nThe `miscsubjects.com` build uses the Object Invocation Protocol (OIP). OIP lets any model that can open a Uniform Resource Locator (URL) act. It uses plain URLs and receipts. There is no persistent session.\n\nOIP differs from the Model Context Protocol (MCP). MCP is an open standard. An AI model connects to an MCP server over a session. A server is a computer program that provides services to other computer programs. The MCP server exposes tools, resources, and prompts. The model can call these. MCP provides a rich, stateful environment for AI models. It is designed for deep interaction within a defined context. MCP is NOT a content-management system.\n\nIn contrast, OIP is stateless. It uses simple HTTP requests. Any system that can make an HTTP request can use OIP. This makes OIP highly flexible and easy to integrate. OIP focuses on direct invocation of objects via URLs. MCP focuses on a persistent session for AI model interaction.\n\n### Reading information\n\nYou can read information from the build. A common read request uses `curl`.\nFor example, to read an article, you would use:\n```bash\ncurl -s https://miscsubjects.com/api/articles/oip-curl\n```\nThe `-s` flag keeps the output quiet. It only shows the response body.\n\n### Writing or running actions\n\nYou can also send requests that change data or run actions. These are called mutating requests. They use specific HTTP methods. These methods include `POST`, `PATCH`, `PUT`, or `DELETE`.\n\nSuch requests need a `Content-Type` header. This header is `Content-Type: application/json`. They also need an `Authorization` header. This header contains a token. A token is a piece of data that proves your identity or authorization. Finally, they include a JavaScript Object Notation (JSON) body.\n\n### Dispatching an object\n\nThe universal way to run an object on `miscsubjects.com` is through the `/api/dispatch` endpoint. An endpoint is a specific Uniform Resource Locator (URL) where an Application Programming Interface (API) can be accessed.\n\nYou can use `POST` to dispatch an object. The request body must be JSON. It needs a `key` and a `body` field.\nThe `key` identifies the object to invoke. The `body` contains the arguments for that object.\n\nExample `POST` dispatch:\n```bash\ncurl -X POST \\\n  https://miscsubjects.com/api/dispatch \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_AUTH_TOKEN\" \\\n  -d '{\"key\":\"example_object_key\",\"body\":\"some arguments for the object\"}'\n```\nThe response includes the result of the invocation. It also includes OIP receipt data. Every invocation lands in an append-only ledger. You can retrieve a receipt for an invocation.\nFor example, if the invocation ID is `inv_12345`:\n```bash\ncurl -s https://miscsubjects.com/api/dispatch?receipt=inv_12345\n```\n\nYou can also use `GET` to dispatch an object. This is for simpler invocations.\nExample `GET` dispatch:\n```bash\ncurl -s \"https://miscsubjects.com/api/dispatch?invoke=example_object_key&body=some%20arguments\"\n```\nNote that arguments in a URL must be URL-encoded.\n\n### Complete curl examples\n\nA complete `curl` example shows all necessary parts. It names the HTTP method. It provides the URL. It lists all headers. It includes the JSON body if applicable. It describes the expected response. It also shows how to get the receipt path.\n\nHere is an example of creating a new article:\n```bash\ncurl -X POST \\\n  https://miscsubjects.com/api/articles \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_AUTH_TOKEN\" \\\n  -d '{\n        \"slug\": \"my-new-article\",\n        \"title\": \"My New Article Title\",\n        \"body\": \"This is the content of my new article.\"\n      }'\n```\nThe response would typically include the newly created article's details and its URL, like `/a/my-new-article`.\n\nHere is an example of updating an existing article:\n```bash\ncurl -X PATCH \\\n  https://miscsubjects.com/api/articles/my-new-article \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_AUTH_TOKEN\" \\\n  -d '{\n        \"title\": \"My Updated Article Title\",\n        \"body\": \"This is the updated content of my article.\"\n      }'\n```\nThe response would confirm the update. It might return the full updated article object.\n\nHere is an example of deleting an article:\n```bash\ncurl -X DELETE \\\n  https://miscsubjects.com/api/articles/my-new-article \\\n  -H \"Authorization: Bearer YOUR_AUTH_TOKEN\"\n```\nThe response would typically indicate success, perhaps with a 204 No Content status.\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 01:15 · model `@cf/meta/llama-3.3-70b-instruct-fp8-fast` · NEEDS WORK · JSON 9/10 · English 8/10 · zero-context human 7/10\n  - gaps named: MCP explanation; Detailed examples of curl usage\n- 2026-07-02 23:40 · model `@cf/meta/llama-3.3-70b-instruct-fp8-fast` · NEEDS WORK · JSON 9/10 · English 8/10 · zero-context human 7/10\n  - gaps named: MCP explanation; Detailed examples of curl usage\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-curl","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:22:16-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:22:16-07:00"}