How to operate the miscsubjects.com build with curl

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

OIP and MCP

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

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

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

Reading information

You can read information from the build. A common read request uses curl. For example, to read an article, you would use:

curl -s https://miscsubjects.com/api/articles/oip-curl

The -s flag keeps the output quiet. It only shows the response body.

Writing or running actions

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

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

Dispatching an object

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

You can use POST to dispatch an object. The request body must be JSON. It needs a key and a body field. The key identifies the object to invoke. The body contains the arguments for that object.

Example POST dispatch:

curl -X POST \
  https://miscsubjects.com/api/dispatch \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  -d '{"key":"example_object_key","body":"some arguments for the object"}'

The 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. For example, if the invocation ID is inv_12345:

curl -s https://miscsubjects.com/api/dispatch?receipt=inv_12345

You can also use GET to dispatch an object. This is for simpler invocations. Example GET dispatch:

curl -s "https://miscsubjects.com/api/dispatch?invoke=example_object_key&body=some%20arguments"

Note that arguments in a URL must be URL-encoded.

Complete curl examples

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

Here is an example of creating a new article:

curl -X POST \
  https://miscsubjects.com/api/articles \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  -d '{
        "slug": "my-new-article",
        "title": "My New Article Title",
        "body": "This is the content of my new article."
      }'

The response would typically include the newly created article's details and its URL, like /a/my-new-article.

Here is an example of updating an existing article:

curl -X PATCH \
  https://miscsubjects.com/api/articles/my-new-article \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  -d '{
        "title": "My Updated Article Title",
        "body": "This is the updated content of my article."
      }'

The response would confirm the update. It might return the full updated article object.

Here is an example of deleting an article:

curl -X DELETE \
  https://miscsubjects.com/api/articles/my-new-article \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN"

The response would typically indicate success, perhaps with a 204 No Content status.