{"slug":"oip-curl-examples","title":"Curl Examples for OIP","body":"## What Curl Examples for OIP Are\n\n`curl` is a command-line tool. It lets you send data to or get data from a server. A server is a computer program that provides services to other programs. `curl` helps you talk to web addresses directly from your computer's terminal.\n\nOIP stands for Object Invocation Protocol. It is a way to make computers do things using simple web links. These links are called endpoints. An endpoint is a specific URL where a server receives requests. `curl` helps you use these OIP endpoints directly. This article shows specific examples of how to do that.\n\n## Why This Build Cares About It\n\nThe miscsubjects.com build uses OIP. `curl` is a direct way to interact with OIP objects. It shows how OIP works without needing a web browser or complex code. This is useful for testing OIP objects. It is also good for automating tasks. `curl` demonstrates a core principle of OIP: any model that can open a URL can act. For more on OIP, see `/a/oip` and `/a/oip-build-overview`.\n\n## How to See or Use It Live with Curl Against https://miscsubjects.com\n\nYou can use `curl` to invoke OIP objects or retrieve information. All examples use `https://miscsubjects.com`.\n\n### Invoking an OIP Object (GET Request)\n\nYou can invoke an OIP object using a GET request to the `/api/dispatch` endpoint. You provide the `key` of the object to invoke and a `body` of data. The `body` is the input for the object.\n\n```bash\ncurl \"https://miscsubjects.com/api/dispatch?invoke=hello-world&body=Hello%20from%20curl%20GET\"\n```\n\nThis command asks the `hello-world` object to process the text \"Hello from curl GET\". The server will respond with the object's output. It will also include an `inv_ID` (invocation ID) in the response. This `inv_ID` is a unique identifier for your request. You can use it later to check the receipt.\n\n### Invoking an OIP Object (POST Request)\n\nYou can also invoke an OIP object using a POST request to the `/api/dispatch` endpoint. This is useful for sending more complex data. You send the `key` and `body` as a JSON (JavaScript Object Notation) object. JSON is a standard format for sending data.\n\n```bash\ncurl -X POST \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"key\":\"hello-world\",\"body\":\"Hello from curl POST example\"}' \\\n  https://miscsubjects.com/api/dispatch\n```\n\nHere, `-X POST` tells `curl` to use the POST method. `-H \"Content-Type: application/json\"` tells the server you are sending JSON data. `-d` provides the JSON data itself. Like with GET, the server responds with the object's output and an `inv_ID`.\n\n### Getting an Article\n\nYou can retrieve the content of an OIP article using the `/api/articles` endpoint. You specify the `slug` of the article.\n\n```bash\ncurl \"https://miscsubjects.com/api/articles?slug=oip-curl-examples\"\n```\n\nThis command fetches the content of this very article. The server returns the article's title and body in JSON format. For more on articles, see `/a/oip-articles-content-plane`.\n\n### Getting a Receipt\n\nAfter invoking an OIP object, you get an `inv_ID`. You can use this ID to retrieve a receipt for your invocation. A receipt is a record of what happened.\n\nFirst, perform an invocation (like the GET or POST examples above) and note the `inv_ID` from the response. Let's assume you got `inv_1234567890abcdef`.\n\n```bash\ncurl \"https://miscsubjects.com/api/dispatch?receipt=inv_1234567890abcdef\"\n```\n\nThis command fetches the receipt for that specific invocation. The receipt confirms that the invocation happened and shows its details. For more details on receipts, see `/a/oip-ledger-receipts`.\n\n## How It Relates to MCP When Relevant\n\nOIP (Object Invocation Protocol) differs from MCP (Model Context Protocol). MCP is an open standard where an AI model connects to an MCP server over a session. The server exposes tools, resources, and prompts the model can call. OIP, however, uses plain URLs and receipts with no persistent session. `curl` directly shows this difference.\n\nWith `curl`, you make a single, independent request. There is no ongoing session to manage. Each `curl` command is a new interaction. This stateless nature is a key feature of OIP. It allows any model or tool that can open a URL to act. MCP, while it might use `curl` internally to call tools, is built around the concept of a session. For a deeper comparison, see `/a/oip-mcp-comparison`.\n\n## Where the Proof Lives\n\nEvery OIP invocation, whether through `curl` or another method, lands in an append-only ledger. This ledger is a permanent record of all actions. A unique receipt is generated for each invocation. You can retrieve this receipt using `curl` with the `inv_ID`, as shown above. The receipt confirms that your invocation was processed and recorded. This ledger and the receipts provide an auditable trail of all OIP activity. You can learn more at `/a/oip-ledger-receipts`.\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:03 · model `gemini/gemini-2.5-flash` · PASS · JSON 9/10 · English 8/10 · zero-context human 8/10\n  - gaps named: oip-owner-auth; oip-create-object\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","dynamic"],"model":null,"ledger":null,"embeds":[],"widgets":[{"type":"stat","value":1,"label":"version"},{"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":"dynamic","count":1,"metric":"version","version":1,"author_model":"gemini/gemini-2.5-flash","revision_source":"subsidiary"},"register":"oip_protocol","status":"published","revisions":0,"contributions":[],"provenance":[{"action":"generate","model":"system/oip_articles","ts":"2026-07-03T00:23:08-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:23:08-07:00"}