Wyldcards API

Use Wyldcards from the wyld command line tool, your own scripts, or any HTTP client through the authenticated API at /api. It is a HAL API: response data is ordinary JSON, while _links tells a client which URL to use next.

Connect a tool

Open this guide from the app: choose API guide at the foot of the API tokens page.

  1. Choose API tokens in the account menu, name a token after the tool that will use it (for example, wyld on my laptop), and choose Create token.
  2. Copy the token straight away. It starts with wyld_ and is shown only once.
  3. In the tool, enter your Wyldcards site URL and the token. For a generic HTTP step, send Authorization: Bearer <token> and Accept: application/hal+json, plus Content-Type: application/json for writes.

A token can do anything your account can. Store it in the tool's encrypted credential store, never in a script's source, a request body, or a URL. Give each tool its own token so you can revoke one without disconnecting the others. A token that has been revoked, or cleared by a password reset, stops working at once. HTTP Basic Auth with a username and password still works, but a token is safer and is the only option for an account that signs in with a passkey.

Use an account dedicated to a script when practical. It keeps the script's access separate from a person's account and can be disabled without disrupting their sign-in.

Claude and other MCP clients

Wyldcards is also a read-only MCP server at /mcp (Streamable HTTP, JSON responses, no session). In Claude, add a custom connector with the address https://wyld.cards/mcp and choose Connect: Claude registers itself, you sign in to Wyldcards if needed and choose Allow, and Claude gets a key (starting wyldmcp_) that works on /mcp alone. Each app you allow is listed under Connected apps on the API tokens page, with Disconnect.

The tools only read: list_stacks, get_stack (a stack's cards in order), read_stack (a stack you can edit as one Markdown document), get_card (a card's fields) and search. They go through the same access checks as the API.

The sign-in is OAuth 2.1 with PKCE (S256) as the MCP authorization spec describes it: the 401 from /mcp names /.well-known/oauth-protected-resource, which names this site's /.well-known/oauth-authorization-server, with dynamic client registration at /oauth/register. Registration accepts Claude's callback and loopback addresses (http://localhost:<port>/callback, for Claude Code and other clients on your computer) only. A client that takes a header instead, such as Claude Code with --header, can send an API token to /mcp as Authorization: Bearer <token>.

Custom code

Send an Authorization: Bearer <token> header and read the response as JSON. Map IDs from the prior response into the next URL, and use a raw JSON body for POST, PATCH, and PUT requests. The standard fetch, Axios, Python requests, Ruby Faraday, and curl clients all work; no SDK or OAuth flow is required.

curl --header "Authorization: Bearer $WYLDCARDS_TOKEN" \
  --header 'Accept: application/hal+json' \
  'https://wyldcards.example/api/stacks'

Adding cards

To add a card to an existing stack:

The shortest route is a single request: POST /api/stacks/{uid}/cards with {"name":"Ada","fields":{"Email":"[email protected]"}}. Every value is validated first; if one is invalid, the answer is 400 and no card is created. GET /api/stacks/{uid}/fields lists the fields a new card gets, with each field's id, name, style, and whether it is required. Date fields accept 2026-09-14 or a full ISO date-time, and checkbox fields accept true/false, yes/no, or 1/0.

To fill in an existing card step by step:

  1. GET /api/stacks and select the stack's uid from _embedded.wyldcards:stacks.
  2. POST /api/stacks/{uid}/cards with {}. Save the returned card id.
  3. GET /api/cards/{id}/parts. Find each field by its stable part id or its name.
  4. Use one PUT /api/cards/{cardId}/fields request to write all values together. Use an exact field name or, preferably, its stable part ID as each key.

A field added to a background appears on every card. Its part ID remains the same, so it is the best value for a script to store. Before the first write, retrieve the parts from any card in the stack, find the field by its name, and save its id in the script's configuration. Do not use a card-specific field ID for a background field. The batch request validates every supplied value before saving any of them, which makes it the safest option for AI-generated records. Field validation, including required and unique fields, applies to API writes just as it does in the editor.

POST https://wyldcards.example/api/stacks/STACK_UID/cards
Accept: application/hal+json
Content-Type: application/json

{}

PUT https://wyldcards.example/api/cards/CARD_ID/fields
Accept: application/hal+json
Content-Type: application/json

{"fields":{"PART_ID":"[email protected]","Company":"Analytical Engines"}}

For a single field, PUT /api/cards/{cardId}/fields/{partId} with {"text":"value"} remains available. The batch response contains the card's current parts and field text.

Working with HAL responses

Collections place their items in _embedded. For example, the stack list is in _embedded.wyldcards:stacks and a card's fields are in _embedded.wyldcards:parts. Relation keys begin with wyldcards:; use bracket notation when a tool does not accept a colon in a property path.

Prefer the URL in _links over constructing a URL yourself. The API may return an absolute URL, which is ready to use as it is. A successful create returns 201 Created; a field validation error returns 400 with a JSON object keyed by the invalid property. Keep that response for troubleshooting.

Other useful requests

The full relation reference is at API link relations.