API¶

Cogitus includes an optional FastAPI server that exposes ideas, groups, and tags over HTTP. It also includes a separate MCP server for read-only tool access from MCP clients.

Install¶

Install the API support extra before trying to serve it:

pip install cogitus[api]

If you are working from a local checkout, the existing development environment already includes the API dependencies.

You only need the api extra on the machine that will serve the API. Using the normal Cogitus TUI against an already running remote server does not require the FastAPI server dependencies.

Run the Server¶

Start the server with:

cogitus api serve

By default, this binds to 127.0.0.1:8000, so it is only reachable locally.

Common options:

cogitus api serve --host 127.0.0.1 --port 8000
cogitus api serve --db-path /path/to/cogitus.db
cogitus api serve --reload

Use --db-path to point the API at a specific Cogitus SQLite database file.

cogitus api serve exposes the REST API only. It does not mount the MCP endpoint.

Configure Authentication¶

Before using the protected API routes, configure the single API user:

cogitus api set-auth --username your-username

This command will prompt for the password and confirmation, hash the password, and save the auth settings in the Cogitus config file.

You can use any username you want here. If you omit --username, Cogitus will prompt for it interactively.

To rotate the JWT signing secret at the same time:

cogitus api set-auth --username your-username --rotate-secret

Authentication Flow¶

The API uses a bearer token flow.

1. Configure credentials with cogitus api set-auth.
2. Request a token from /api/v1/auth/token.
3. Send that token in the Authorization: Bearer ... header.

Fetch a token:

curl -X POST http://127.0.0.1:8000/api/v1/auth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=your-username&password=your-password"

Example token response:

{
  "access_token": "eyJhbGciOi...",
  "token_type": "bearer"
}

Access tokens expire. By default, Cogitus issues tokens valid for 30 minutes.

You can change the lifetime with the api_auth_token_expire_minutes setting in the Cogitus config file. After a token expires, request a new one from /api/v1/auth/token.

Use the token against a protected route:

curl http://127.0.0.1:8000/api/v1/ideas \
  -H "Authorization: Bearer eyJhbGciOi..."

When the Cogitus TUI is using remote mode, it handles this token flow for you. If the access token expires, the client reauthenticates once and retries the request automatically.

MCP Server¶

Cogitus can also run a dedicated MCP server for read-only access to the same idea database. This is separate from the REST API server:

• cogitus api serve exposes REST routes on port 8000 by default.
• cogitus mcp serve exposes only /mcp on port 9000 by default.
• MCP tokens are separate from normal API login tokens.

Create a token for your MCP client:

cogitus mcp token

The command prints the full Bearer ... value. It also creates and saves an MCP signing secret if one is not already configured. MCP tokens are valid for 90 days by default; set mcp_auth_token_expire_days to explicitly choose a different lifetime.

To rotate the MCP signing secret and print a new token:

cogitus mcp token --rotate-secret

Rotating the secret invalidates previously issued MCP tokens.

Start the MCP server:

cogitus mcp serve

Common options:

cogitus mcp serve --host 127.0.0.1 --port 9000
cogitus mcp serve --db-path /path/to/cogitus.db
cogitus mcp serve --reload

Configure the MCP client to connect to:

http://127.0.0.1:9000/mcp

Use the printed Bearer ... token as the MCP request authorization value.

The MCP server currently exposes these read-only tools:

• get_idea_refs
• get_single_idea
• get_group_names
• get_tag_names

Agent Guidance¶

If you use Cogitus MCP with coding agents, consider adding a short note to the project's local agent guidance file, such as AGENTS.md, CODEX.md, or the equivalent file for your agent tool.

Useful guidance is:

• Cogitus MCP is read-only for now.
• Use it for existing project context, TODO/idea lookup, and notes already stored in Cogitus.
• Use get_idea_refs first, then get_single_idea only for ideas that need full body text.
• Use query filters such as group:cogitus, tag:bugs, or group:cogitus and tag:search.
• Do not use it instead of reading current repo files when the question is about the live codebase.

The MCP app does not expose the normal REST API routes, /docs, or /openapi.json.

Use Cogitus with a Remote Server¶

Before switching a local Cogitus app into remote mode, make sure the remote API server is already configured and running.

Recommended order:

1. On the server machine, install the API extra with pip install cogitus[api] if needed.
2. Point the server at the correct SQLite file with cogitus api serve --db-path ... if you are not using the default database.
3. Configure API auth with cogitus api set-auth.
4. Start the API with cogitus api serve.
5. On the client machine, open Cogitus and press Ctrl+P to open the command palette.
6. Run Backend settings.
7. Choose Remote API and enter the server URL, username, and password.
8. Save the settings.

Cogitus also keeps the existing hidden c shortcut for this dialog, but the command palette is now the primary entry point.

After saving, the app title changes to Cogitus [remote]. Local mode shows Cogitus [local].

Remote Mode Behavior¶

• Cogitus keeps a local cache database at ~/.config/cogitus/cogitus-remote-cache.db while in remote mode.
• It syncs the cache when the app starts, when the main screen regains focus or resumes, and every 60 seconds while the main screen is active.
• Opening edit-style flows refreshes from the server first, so you usually start from the latest remote copy.
• Background syncing is paused while a modal screen is open.
• Writes update the local cache immediately after a successful API request.

Clone Remote To Local¶

Remote mode also exposes a separate Clone Remote To Local command in the command palette.

That command is different from normal remote cache sync:

• normal remote sync refreshes the remote cache database used by the active remote session
• Clone Remote To Local downloads a remote snapshot and overwrites the normal local database

Use this when you want a local-mode copy of the current remote data. See Remote Clone for the full workflow and caveats.

Conflict Handling¶

• Remote idea updates use optimistic locking based on the idea's last known updated_at value.
• If another client changes the same idea before you save, the server returns 409 Conflict.
• Today, Cogitus does not attempt automatic merges. Reopen or retry the edit after reviewing the latest remote version.

Current Caveats¶

Available Routes¶

The current API exposes:

• /api/v1/auth/token for bearer-token login

Protected authenticated routes include:

• /api/v1/ideas
• /api/v1/groups
• /api/v1/tags
• /api/v1/snapshot for remote cache bootstrap

It also exposes:

• /health for a simple health check
• /docs for the interactive FastAPI docs
• /openapi.json for the OpenAPI schema

The MCP server is separate and exposes only /mcp.

Example Output¶

Health check:

curl http://127.0.0.1:8000/health

{"status":"ok"}

List ideas:

curl http://127.0.0.1:8000/api/v1/ideas \
  -H "Authorization: Bearer eyJhbGciOi..."

[
  {
    "pk": 1,
    "created_at": 1743157200,
    "updated_at": 1743157200,
    "title": "Ship FastAPI API",
    "body": "Expose ideas, groups, and tags over HTTP.",
    "group": {
      "pk": 1,
      "created_at": 1743157200,
      "updated_at": 1743157200,
      "name": "default"
    },
    "tags": [
      {
        "pk": 1,
        "created_at": 1743157200,
        "updated_at": 1743157200,
        "name": "api"
      }
    ]
  }
]

Notes¶

• /api/v1/ideas, /api/v1/groups, and /api/v1/tags now require a valid bearer token.
• The ideas list endpoint also accepts limit, offset, and query parameters.
• The API uses the same SQLite-backed data model as the local app.
• Server auth configuration is currently stored in the normal Cogitus config file.
• MCP auth uses a separate bearer token and signing secret.
• This is still intended for light use today, not heavy multi-user deployment.