What is an API?

What this article explains

An 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.

Plain words

A 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.

Introduction to MCP and OIP

MCP (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.

OIP (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.

OIP 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.

How APIs work in OIP

OIP 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.

A 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.

For example, to invoke an object, you can use the /api/dispatch route. Use a POST method. Send a JSON body with the key and body fields. You can also use a GET method. Pass the invoke and body parameters as query strings.

Every invocation lands in an append-only ledger. A receipt is issued. * The receipt for an invocation can be retrieved using the /api/dispatch route. Use a GET method. Pass the receipt parameter.

Other OIP routes allow reading content. To read an article by its slug, use the /api/articles route with a GET method. Pass the slug parameter. To directly access an article, use the /a/<slug> route.

Using curl with OIP

You 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.

Here are detailed curl examples for common OIP operations:

1. Invoke an object using POST: This sends a JSON payload to the /api/dispatch route.

curl -X POST \
  -H 'Content-Type: application/json' \
  -d '{"key":"your_object_key","body":"your_object_input"}' \
  https://miscsubjects.com/api/dispatch

2. Invoke an object using GET: This passes the object key and body as URL query parameters to the /api/dispatch route.

curl 'https://miscsubjects.com/api/dispatch?invoke=your_object_key&body=your_object_input'

3. Retrieve an invocation receipt: After an invocation, you get an inv_ID. Use this ID to check the ledger.

curl 'https://miscsubjects.com/api/dispatch?receipt=inv_ID_from_previous_invocation'

4. Read an article using the API: This retrieves article data in JSON format.

curl 'https://miscsubjects.com/api/articles?slug=oip-api'

5. Read an article directly: This accesses the human-readable page for an article.

curl 'https://miscsubjects.com/a/oip-api'

Latest clarity reviews (live)

Fresh 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.

• 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

- gaps named: MCP explanation; Detailed curl usage examples

• 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

- gaps named: MCP explanation; Detailed curl usage examples

How 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.