Incantory
Sign in

Getting started

Create an API token, fetch a prompt with curl, then use the TypeScript SDK, the Python SDK or the CLI.

Public prompts can be read without an account. You need a token to read your own private or unlisted items, and to write anything.

Create a token

  1. Sign in and open Settings → Security.
  2. Under API tokens, create a token and pick its scopes:
    • read: read prompts, makes and your private content.
    • write: create and update prompts, versions and labels (implies read).
    • evals:write: report eval runs from CI (implies read).
  3. Copy the token. It starts with inc_ and is shown once; the server keeps only its hash.

Send it as a bearer token:

bash
export INCANTORY_TOKEN=inc_...
curl -H "Authorization: Bearer $INCANTORY_TOKEN" https://incantory.ai/api/me

In CI, prefer the CLI's device login on your own machine and an INCANTORY_TOKEN secret in the pipeline.

Fetch a prompt with curl

A prompt with its latest version (metadata, labels, files, variables):

bash
curl https://incantory.ai/api/v1/prompts/alice/code-review

The version a label points at, or a pinned version:

bash
curl "https://incantory.ai/api/v1/prompts/alice/code-review?label=production"
curl https://incantory.ai/api/v1/prompts/alice/code-review/versions/3

Just the entry file as plain text:

bash
curl "https://incantory.ai/api/v1/prompts/alice/code-review/raw?label=production"

Version responses are immutable and carry an ETag, so repeated requests with If-None-Match get 304 Not Modified. See the REST API reference for everything else.

TypeScript

bash
npm install @incantory/sdk
ts
import { Incantory } from '@incantory/sdk';

const inc = new Incantory(); // token from $INCANTORY_TOKEN, optional for public prompts
const prompt = await inc.prompts.get('alice/code-review@production');
console.log(prompt.ref); // alice/code-review@v7
console.log(prompt.text({ language: 'Go', code: 'x := 1' }));

More in the TypeScript SDK guide.

Python

bash
pip install incantory

Until the package is on PyPI, install it from a checkout of the repository with pip install ./sdk/python.

python
from incantory import Incantory

with Incantory() as client:  # token from INCANTORY_TOKEN
    prompt = client.prompts.get("alice/code-review@production")
    out = prompt.render({"language": "Go", "code": "x := 1"})
    print(out.text)

More in the Python SDK guide.

CLI

bash
npx incantory login
npx incantory render alice/code-review@production --var language=Go --var [email protected]
npx incantory add alice/code-review@production --to claude

login runs a device flow in your browser and stores the token in ~/.config/incantory/credentials.json. More in the CLI guide and Install into tools.

Next steps