Anthropic’s surface centers on a few clearly related resource types: Models, Messages (single), Message Batches (bulk/async), Files, and Skills (with Skill Versions). Understand those relationships and the few cross-cutting differences (stable vs beta endpoints, pagination tokens, and workspace-scoped operations) and you can handle the common user requests cleanly.

How the domain is organized

• Models are read-only descriptors you choose when generating text. Use model IDs (aliases) from models.list / models.get to pick the model for completions or messages.

• Messages vs Message Batches:

  • messages.post sends a single synchronous message/turn and returns the response in one call.
  • message_batches is a separate workflow for sending many messages/inputs as a single batch. Creating a batch returns a batch object; results for each item are retrieved from a dedicated results endpoint. Batches are cancelable and deletable as a unit.

• Files are storeable artifacts (uploads, metadata, downloads). Upload to create a file_id, then reference that file_id from other operations that accept file artifacts (skill versions, exports, etc.). File operations include upload_file, get_file_metadata, download_file, and delete_file.

• Skills are first-class objects you create and manage. Each Skill can have multiple Skill Versions. Versions are immutable snapshots identified by a version identifier (not a semantic name) — the version identifier is a Unix epoch timestamp string. You create a Skill, create one or more Skill Versions, list versions, and delete specific versions or the whole Skill.

Typical entry points

Start with these calls to get the IDs you will need for other operations:

• To pick a model: call models.list (or models.get if you already have an alias) to obtain a model_id or confirm model capabilities.

• To manage Skills: call list_skills to find skill_id values. After you have a skill_id, call list_skill_versions to see available version IDs (the version strings are Unix epoch timestamps). To create a new deployable, call create_skill then create_skill_version for that skill_id.

• To work with Files: call upload_file to produce a file_id. Use list_files or get_file_metadata to discover existing file_ids. Use download_file to fetch content and delete_file to remove it.

• To run many messages at once: create a batch with message_batches_post and use message_batches_results to obtain per-item outcomes. You can cancel a running batch or delete it after you're done.

• For single-turn usage: messages.post or complete.post are the straightforward entry points for user requests that ask for a generated reply.

Common user tasks and the required steps

1. Create and use a Skill (typical user flow)

• Create the Skill with create_skill (returns skill_id).
• If you need artifacts (code, prompts, data), upload them with upload_file and keep the returned file_ids.
• Create a Skill Version with create_skill_version for the skill_id. Provide any file_id references the version requires. The response contains the version identifier (an epoch timestamp string).
• Call get_skill_version to inspect a version or list_skill_versions to enumerate them.
• Delete a specific version with delete_skill_version by passing the exact version identifier. Delete the whole Skill with delete_skill.

2. Run a single message or completion

• Choose a model_id from models.list / models.get.
• Call messages.post (or complete.post for completion-style requests) with the chosen model_id and message content.
• To estimate cost or input size beforehand, use messages.count_tokens with the same message structure.

3. Run large/parallel workloads with Message Batches

• Create the batch with message_batches_post supplying an array of inputs.
• The batch object indicates state; fetch the batch with message_batches_retrieve for metadata and status.
• Use message_batches_results to obtain per-item results (this is the endpoint that returns the actual outputs for each message in the batch).
• If needed, message_batches_cancel will attempt to stop processing; message_batches_delete removes batch metadata.

4. Upload and use files

• Call upload_file to create files (returns file_id and metadata).
• Use get_file_metadata or list_files to locate file_ids for reuse.
• download_file returns raw content (string) for the file.
• delete_file removes the file and metadata.

Pagination and page-token nuances

• Two pagination styles appear across endpoints: cursor-style (before_id / after_id) and token-style (page / next_page).
  • Use before_id/after_id for endpoints that return those cursors (files, message batches list, models list in some variants).
  • Use page/next_page for skill lists and skill-version lists where the response provides a page token.
• Default limits vary (commonly 20) and some endpoints accept a limit up to 1000. Read the list response to know which token to pass next.

Beta vs stable endpoints

• There are both beta-prefixed endpoints and stable counterparts. They mirror functionality but responses and available request fields can differ. When you need the latest beta capabilities, call the beta path; otherwise prefer the stable endpoint names.
• Many endpoints expose an anthropic-version or anthropic-beta header to select behavior. When a specific behavior or field is required by the caller (e.g., new beta fields in requests or responses), include the corresponding version/beta header.

Authentication and workspace-scoped operations (what to watch for)

• Some resources are workspace-scoped and require the workspace API key header. File operations, message-batch deletes/results, and certain model/info endpoints commonly show an x-api-key header in their interface. If a call returns an authorization error or the response indicates workspace scope, include the workspace x-api-key header in subsequent calls.

Non-obvious, important gotchas

• Skill Version IDs are not human-friendly names — they are Unix epoch timestamps serialized as strings. When you create a version you must use the exact timestamp string to reference or delete it.

• Creating a batch and retrieving its results are separate steps: the batch creation response does not contain per-item outputs. Always call the results endpoint for the outputs of individual messages in the batch.

• The download_file endpoints return raw content as a string (not an object). Expect to find the file payload directly in the response body.

• Token counting and the actual send call use the same messaging structure. Use messages.count_tokens to preview token usage with the exact message payload you will send to messages.post or message_batches_post.

• Pagination token names differ by resource. Don’t assume page works everywhere—inspect the list response to see whether it returned next_page (token-style) or after_id/before_id (cursor-style) and pass the same token name back.

• Beta vs stable responses can differ in shape and field names. If a client or caller expects a particular field, confirm which endpoint version (beta vs stable) provides it.

Quick decision checklist

• Need a model? Call models.list/models.get to obtain model_id.
• Need to upload or reference artifacts? Call upload_file → use returned file_id in later calls.
• Need to run a single prompt? Use messages.post or complete.post with an appropriate model_id.
• Need many parallel prompts? message_batches_post → poll message_batches_results → optionally cancel or delete.
• Need to create an automated extension? create_skill → create_skill_version (versions are epoch timestamps).

Use these patterns as the operational map: models supply compute targets; files supply artifacts; skills + skill versions are deployable logic/artifact bundles; messages and message batches execute work. Following the entry points above will get you the IDs required by downstream calls and avoid the common pagination/versioning pitfalls.