Introduction: Why Use the REST API with cURL?

Welcome back! So far, you have learned how to send messages to Claude using the Python and JavaScript SDKs. These SDKs are great if you are working in those languages, but what if you want to use a different language, or you want more direct control over your requests? That’s where the REST API comes in.

The REST API lets you talk to Claude from any programming language or tool that can make HTTP requests. One of the most common tools for this is cURL, a command-line utility that lets you send HTTP requests right from your terminal. In this lesson, you will learn how to use cURL to send a message to Claude, just like you did with the SDKs.

Before we dive in, it’s good to know that Anthropic also provides SDKs for Java, Go, and Ruby. But if you ever need to work outside these languages, or just want to see what’s happening “under the hood,” the REST API is the way to go.

What You Need to Get Started

To use the Claude REST API, you need two main things:

  • An API key: This is a secret code that tells the API who you are and that you have permission to use it. You should have received this key when you signed up for access to Claude.
  • The API endpoint: This is the web address where you send your requests. For Claude, the default endpoint is:

On CodeSignal, you don’t need to worry about installing cURL or setting up your API key — the environment is already set up for you. However, if you want to try this on your own computer, you will need to install cURL and set your API key as an environment variable for security.

Breaking Down the cURL Request

Let’s build up the cURL request step by step. We’ll start with the basic structure and add each part one at a time.

1. The Basic cURL Command

At its simplest, a cURL command to send a POST request looks like this:

Here, -X POST tells cURL to use the POST method, which is used to send data to the server.

2. Adding the Endpoint

For Claude, the endpoint is https://api.anthropic.com/v1/messages. So, the command becomes:

3. Adding Headers

APIs often require headers to provide extra information. For Claude, you need three headers:

  • Your API key
  • The API version
  • The content type (JSON)

Here’s how you add them:

  • x-api-key is your secret key (here, we use an environment variable for safety).
  • anthropic-version tells the server which version of the API you want to use.
  • content-type tells the server you are sending JSON data.
4. Adding the Data Payload

Now, you need to tell Claude what you want it to do. This is done by sending a JSON object with your message and some settings.

Here’s the data you’ll send:

  • model specifies which Claude model to use.
  • max_tokens limits the length of the response.
  • messages is a list of messages in the conversation. Here, you send a single message from the user: “Hello, world.”

To add this data to your cURL command, use the --data flag:

This is the full command you need to send a message to Claude using cURL. Note that we're using the jq command line tool to format the output as JSON data.

A likely response might look like this:

Customizing Your Request

You can easily change the message or model in your request. For example, if you want to ask Claude a different question, just change the content field:

If you want to use a different model, change the model value. Always check the documentation for available models.

Tip:
Using environment variables (like $ANTHROPIC_API_KEY) helps keep your API key safe. Never put your API key directly in your code or share it with others.

Review And What’s Next

In this lesson, you learned how to send a message to Claude using the REST API and cURL. You saw how to build the request step by step, add the necessary headers, and send your message as JSON data. You also learned how to customize your request and keep your API key secure.

Now you are ready to practice these steps on your own. In the next exercises, you will get hands-on experience sending different messages to Claude using cURL. This will help you understand how the REST API works and give you the flexibility to use Claude from any environment or programming language. Good luck!

Sign up
Join the 1M+ learners on CodeSignal
Be a part of our community of 1M+ users who develop and demonstrate their skills on CodeSignal