API

The API is Merulan's HTTP Surface. Use it when an integration needs an admitted resource method.

Set up access

Start with API authentication to exchange a credential and select a Workspace. Then open the generated API reference. It names each admitted method's verb, path, credential, Workspace scope, permission, request, result, and terminals. A route seen elsewhere is not an HTTP contract.

Authentication and Workspace scope

Send the supported bearer credential in the Authorization header. Each method needs one Workspace and the caller's permission. Choose a Workspace the caller can access. A request body cannot widen access. The method page states the exact scope and permission.

How the API works

The API uses documented /api/v1 routes. Read a method page before you make a request. The page is generated from the admitted contract. It keeps its parameters, body, result, and failure terminals current.

Request conventions

Use the method's verb and path exactly. Put a path value only in the path. Send query values only when the method lists them. Send a body only when its page defines one. Treat results and failures as typed terminals. Do not use a shared error list.

Pagination and concurrency

Some list methods declare limit and offset. Use only the values and bounds on that method. Use its returned pagination facts to choose the next page. Not every read is paginated. If a write has a durable request identity, keep it after an uncertain call. Read its conflict terminal and readback before a different write. A method without this contract does not promise safe replay.

Terminals and readback

A successful response is only the method's declared terminal. For a write, follow its generated readback link. It shows the resource or reacquires durable work. For a retryable failure, fix the cause or wait as the method says. Otherwise, use readback and the failure terminal before you repeat an uncertain request.

First call

Use this supported read to confirm credentials, Workspace scope, and readback in one request. First obtain a List identifier from a permitted Workspace. Then call the generated Get list method, substituting your API origin, credential, and List identifier:

MERULAN_API_ORIGIN is the API origin you call. MERULAN_API_CREDENTIAL is the access token from Authentication. MERULAN_WORKSPACE_ID is the Workspace the request acts in. LIST_ID is the List identifier you obtained.

curl "$MERULAN_API_ORIGIN/api/v1/lists/$LIST_ID" \
  -H "Authorization: Bearer $MERULAN_API_CREDENTIAL" \
  -H "x-merulan-workspace-id: $MERULAN_WORKSPACE_ID"

The method's success terminal returns that List. If it fails, use the method page to tell a missing List from an access or scope problem. Check the Workspace and caller permission. Then read the List again. Do not guess whether the request changed state.

When it fails

A declared failure terminal

Cause: an API request reached a method failure terminal. Recovery: read the terminal on that method page. Fix a request-shape problem before a new request. For an access or scope problem, use a credential and Workspace with the required permission. Retry only when the terminal says the failure is retryable.

An uncertain durable write

Cause: an API request ended before its terminal was seen. Recovery: keep the method's durable identity. Use its generated readback. Inspect its conflict terminal before another write. Do not create a new identity to make the request appear successful.

Reference

• The generated API reference is the entry point for admitted resources and methods. Use it to obtain exact HTTP contracts.
• Lists explains the product object read by the first call. Its API method page remains the HTTP authority.