Claude Projects: What They Are and How to Build the Same Workflow via API

When people ask what projects in Claude are, they mean a claude.ai feature: a workspace where documents and instructions are uploaded once and all chats inside it "remember" that context. The API has no ready-made "Project" button, but the same scenario is built from three parts: a persistent system prompt, documents in context and prompt caching. Let's look at how it works, how to reproduce it and what it costs.

What Claude Projects are

According to Anthropic's help center, projects in claude.ai are self-contained workspaces with their own chat histories and knowledge bases. Inside a project you can:

• upload documents, text and code as project knowledge: Claude uses them to better understand the context of your chats;
• set project instructions, for example to answer in a formal tone or from the perspective of a certain role;
• hold separate chats that do not mix with the rest.

On paid plans, when there is too much knowledge for the context, a retrieval mode (RAG) kicks in and extends capacity up to about ten times. On team plans, projects can be shared with colleagues. Anthropic is also rolling out a new beta version of projects, where a project becomes one conversation with parallel cloud threads, starting with Claude Code. Plan terms and limits change, so check the help center on the service's website.

What matters for you is the essence: a project gives the model a permanent set of instructions and documents at the start of every chat. That is what you need to reproduce.

How a project maps to API parts

The main difference: in claude.ai the platform stores chats and documents for you, while in the API your code does. In return you choose the model, see a per-token bill and can store data anywhere.

A permanent prefix and prompt caching

If every request resends 50,000 tokens of documents, you pay for them each time. Prompt caching solves this: the stable prefix of the request is marked, and later requests read it at a reduced price. In the Anthropic format (POST /v1/messages, the Anthropic SDK) the gateway sees how much input came from cache and charges the read price instead of the input price. Cache writes are billed separately and cost more than input.

A Python example with the official Anthropic SDK. The address has no /v1 because the SDK adds it itself:

import os
import anthropic

client = anthropic.Anthropic(
    base_url="https://api.zukko.pro",
    api_key=os.environ["ZUKKO_API_KEY"],
)

INSTRUCTIONS = "You are a legal department assistant. Answer briefly and cite the contract clause."
KNOWLEDGE = open("knowledge.txt", encoding="utf-8").read()  # project documents

history = []

def ask(question: str) -> str:

The cache_control marker goes on the last block of the stable part. Everything up to it lands in the cache, while questions and history come after. If cache_creation_input_tokens in the response is non-zero, the prefix was written, and cache_read_input_tokens shows how much was read from cache.

A few rules that save money:

1. Keep the prefix unchanged: any text change before the marker resets the cache. Put dates, user names and other changing data after the documents.
2. The cache lives for a limited time (by default around five minutes, refreshed on every hit). Questions once an hour do not use the cache.
3. There is a minimum cacheable prefix length that depends on the model. For short instructions the cache will not trigger, and that is normal. See Anthropic's documentation for details.
4. Note that for Claude the discount comes specifically from the Anthropic format. In the OpenAI format (/v1/chat/completions) all Claude input is billed at the input price.

A detailed breakdown of fields and responses is in the documentation on Messages↗ and on key limits and cache↗. Two more articles on the topic: prompt caching: reads and writes↗ and saving with the cache↗.

Calculation: what the cache gives

Prices as of October 18, 2026, claude-sonnet-5-5: input $0.4, output $2, cache read $0.05, cache write $0.5 per 1M tokens. Scenario (hypothetical): documents and instructions of 50,000 tokens, 100 questions in a row, each with 200 new input tokens and a 500-token reply. For simplicity we assume each question starts a new chat with no accumulated history: in the code above the history grows, so input per step will be larger.

Without cache. All input is billed at the input price: 100 × 50,200 = 5,020,000 tokens, which is 5.02 × 0.4 = $2.008. Output: 100 × 500 = 50,000 tokens, 0.05 × 2 = $0.10. Total about $2.11.

With cache. The first request writes the prefix: 0.05 × 0.5 = $0.025. The remaining 99 requests read it: 99 × 50,000 = 4,950,000 tokens, 4.95 × 0.05 = $0.2475. New input: 100 × 200 = 20,000 tokens, 0.02 × 0.4 = $0.008. Output is the same $0.10. Total 0.025 + 0.2475 + 0.008 + 0.10 = $0.3805, about $0.38.

This is an illustration on an invented volume, assuming all requests fall within the cache lifetime. The real picture depends on the intervals between questions. Current prices: GET https://api.zukko.pro/v1/models or the Models page in the dashboard.

If documents exceed the context

The context of claude-sonnet-5-5 is 1M tokens, so most project knowledge bases fit entirely. If yours does not, you need search: split documents into chunks, find the relevant ones for the question and put only those into the request. The prefix is then no longer constant and the cache works less well. A reasonable compromise: keep short instructions and the key reference in the cached prefix and mix in the rest through search.

What stays with you

Chat storage, access rights and collaboration are not provided out of the box in the API: you will build your own table of chats and users. In return you get model choice. Compare by price, context and strength index and test on your own tasks: for bulk answers from a reference, a cheaper model is sometimes enough.

To try it, create a key in the dashboard↗, put your documents into a file and run the code above. The balance is topped up from $1 via SBP, a MasterCard card or cryptocurrency.

FAQ

Do API projects replace a Claude subscription?

They are different things: a subscription gives the claude.ai interface, while the API is billed per token. The project's functionality is reproduced in code, but the chat interface and collaboration you build yourself.

Do I need the cache if my documents are small?

If the prefix is shorter than the minimum cacheable block, the cache will not turn on. Then it is enough to pass the documents in system.

Does it work in the OpenAI format?

Yes, but for Claude the cache discount does not apply in that format. For GPT models, cache reads are visible in both formats through prompt_tokens_details.cached_tokens.

How do I keep spending under control?

Create a separate key per project with daily and monthly dollar limits and a list of allowed models.