Assessment of Anthropic’s existing API documentation
Audit performed 3/27/2024.
Create a Message.
Create a Message.
Send a structured list of input messages with text and/or image content, and the model will generate the next message in the conversation.
The Messages API can be used for for either single queries or stateless multi-turn conversations.
Note: OpenAI’s Chat API description is clearer:
Given a list of messages comprising a conversation, the model will return a response … Creates a model response for the given chat conversation.
How are the endpoints grouped? (Are they listed all on the same page, or on different pages? Are they grouped by method, or by resource?)
There is only a single endpoint POST /messages
(as of 3/27/2024).
How are the methods specified for each endpoint?
The method is listed in front of the specific endpoint.
A screenshot of Anthropic's Claude API POST /messages endpoint (accessed 3/27/2024). Source: https://docs.anthropic.com/claude/reference/messages_post
There are 3 header parameters: x-api-key
, anthropic-version
, content-type
.
The x-api-key
and content-type
header parameters are explained in section https://docs.anthropic.com/claude/reference/getting-started-with-the-api.
The anthropic-version
parameter (2023-06-01, 2023-01-01) is explained in section https://docs.anthropic.com/claude/reference/versions.
The anthropic-version
parameter can cause confusion, as the endpoint states v1 https://api.anthropic.com/v1/messages. Why is this not v2?
There are no path nor query string parameters.
There is a long list of request body parameters: name, data type, required/blank.
Examples are provided for the messages request body parameters and also in section https://docs.anthropic.com/claude/reference/messages-examples.
max_tokens
: It should clarify that this is only for the generated model response, and not shared with the context window (this differs from OpenAI’s API: The total length of input tokens and generated tokens is limited by the model’s context length).
stream
: Clarify whether this is only for SDK API calls?
top_p
: Needs to specify range and default value.
top_k
: Needs to clarify if it can be used with top_p or temperature? Needs to specify range and default value.
Yes, the data type and required/optional value are defined for each request body parameter.
The example request is show in cURL, Python, and JavaScript.
The example request includes 3 header parameters and 3 body parameters (all required).
A screenshot of Anthropic's Claude API POST /messages endpoint example request (accessed 3/27/2024). Source: https://docs.anthropic.com/claude/reference/messages_post
Yes, there is a sample response and schema.
Children are nested directly inside the parent section.
A screenshot of Anthropic's Claude API POST /messages endpoint response content property (accessed 3/27/2024). Source: https://docs.anthropic.com/claude/reference/messages_post
However, there appears to be inconsistent formatting (see content vs. usage).
A screenshot of Anthropic's Claude API POST /messages endpoint response usage property (accessed 3/27/2024). Source: https://docs.anthropic.com/claude/reference/messages_post
Compared with OpenAI’s API, the nesting is more consistent with the Show and Hide properties toggle.
A screenshot of OpenAI’s API chat response example and schema (accessed 3/27/2024). Source: https://platform.openai.com/docs/api-reference/chat/object
Based on the 13 DX Criteria by Adam DuVander at EveryDeveloper.
Yes, SDKs in Python and JavaScript/TypeScript are available at https://docs.anthropic.com/claude/reference/client-sdks.
There is a getting started guide at https://docs.anthropic.com/claude/reference/getting-started-with-the-api, but not in-depth.
Yes, self sign up for API console access is available.
Yes, pricing information is available at https://www.anthropic.com/api. Providing some benchmarking of number of tokens equating to outcomes would be helpful. Clarify the token charges on both input and output. The plan tiers can be better presented.
Currently, there is an offer for claiming free credits for API usage, but it is only called out inside the API console. Perhaps it can be displayed on pricing page.
Email support is available at support@anthropic.com.
Turns out there is a Discord community server at https://www.anthropic.com/discord but it is hidden at the bottom of the page at https://docs.anthropic.com/claude/docs/intro-to-claude.
API status information isn’t displayed currently.
Unable to ascertain if Anthropic’s API reference is auto-generated from an OpenAPI Specification file.
There are no sample applications featured, but examples of messages and SDKs are available.
There are news posts at https://www.anthropic.com/news but not developer posts currently.
There is copy and paste functionality along with sample request and response, but not interactive cURL calls.
Anthropic’s top navigation menu does feature an option for API, which leads to the Claude API page.
A screenshot of Anthropic's Claude API landing page (accessed 3/27/2024). Source: https://www.anthropic.com/api
However, the link to the API documentation is obscurely hidden in the Build plan information.
A screenshot of Anthropic's Claude API plan tiers (accessed 3/27/2024). Source: https://www.anthropic.com/api
The API navigation menu should have submenus for Pricing/Models and API Documentation.
Yes, example cURL call is available at https://docs.anthropic.com/claude/reference/messages_post. However, users need to provide their own API keys as no test API keys are available.