APIs and integrations

Module: 5, Technical tools | Time: about 30 min reading + 25 min practice

The gist

An API is the language programs use to talk to each other. Imagine that every service (Stripe, Gmail, Slack, a CRM) is a country with its own language. An API is the interpreter and the diplomatic protocol at the same time. Claude Code knows this language and talks to any service on your behalf.

Key concepts

• API (Application Programming Interface): a standardized way for programs to communicate
• REST API: the most common type: a URL + a request method + data in JSON
• Claude Code builds tools that make API calls
• Integrations = workflows + tools for external services

Theory

What an API is, without the jargon

When you open WhatsApp and see new messages, the app reaches out to WhatsApp's servers through an API: "give me the messages for user X." The server replies with a list of messages. That's an API in action.

The waiter analogy: you sit at a table (your app), and the waiter (the API) goes to the kitchen (the server) with your order and brings back the food (the data). You don't walk into the kitchen yourself, and you don't need to know how everything works back there.

Why this matters for you: most of the tools a business wants to automate have an API. Stripe takes payments through an API. SendGrid sends emails through an API. Notion stores tasks behind an API. If a service has an API, Claude Code can work with it.

REST API: how requests work

🎨 Picture this: a REST API is a standard application form. The structure is the same everywhere: who it's for, what I'm asking for, my details, my signature. It doesn't matter which bank or government office it is, the form is the same. Learn to fill out one and you can fill out all of them.

Most modern APIs are REST APIs. A request is made of:

1. URL (address)

https://api.stripe.com/v1/customers

This is the address of the resource. Like a street address: you know where to go.

2. Request method

• GET: get data ("give me the list of customers")
• POST: create something new ("create a new customer")
• PUT / PATCH: update something that exists ("change the customer's email")
• DELETE: delete ("delete the customer")

3. Data in JSON format

{
  "email": "[email protected]",
  "name": "Alex Johnson",
  "plan": "premium"
}

JSON is text inside curly braces. Readable, structured. Like a filled-out form.

4. Headers The request's metadata: who you are, what format you expect, an authorization token.

API keys: how authorization works

🎨 Picture this: an API key is a pass into a factory. Without it, the guard won't let you in. With someone else's pass, you walk in as another employee and can cause trouble in their name. That's why nobody leaves their pass lying around at the front desk.

Most APIs require a "pass": an API key. It's a long string of characters that identifies you as an authorized user.

Example: a Stripe key looks like sk_live_AbCdEfGh1234... (a long string of characters).

A critically important rule: API keys are like passwords. Never, under any circumstances, paste them directly into your code. If a key ends up on GitHub, attackers can charge money to your Stripe account or send spam through your SendGrid.

The right way to store them:

# .env file (local)
STRIPE_SECRET_KEY=sk_live_AbCdEfGh1234...
SENDGRID_API_KEY=SG.xyz...
TELEGRAM_BOT_TOKEN=1234567890:AbCdEf...

The .env file is added to .gitignore (so it never gets into the repository). The code uses process.env.STRIPE_SECRET_KEY: a reference to the variable, not the key itself.

Claude Code usually follows this rule and doesn't put keys in code, but still review the changes before every commit and check that no keys are in them.

Testing an API

Before building an API into a workflow, you check that it works. This is called a "test request."

With curl (in the terminal):

curl -X GET "https://api.stripe.com/v1/customers?limit=3" \
  -H "Authorization: Bearer sk_test_..."

With Postman / Insomnia: graphical tools where you can send requests through an interface, without the command line.

With Claude Code: you just say "send a test request to the Stripe API and show me what it returns," and the agent writes and runs the request itself.

Error handling: the reality of API integrations

🎨 Picture this: API response codes are like a traffic light. 200 is green, go. 401 is red, no pass. 429 is yellow, slow down, you're going too fast. 500 is a crash at the intersection: not your fault, wait.

APIs don't always respond successfully. Response codes:

Rate limiting is a cap on the number of requests. For example, Stripe has an overall limit on requests per second in live mode, and a lower one in the sandbox (the numbers change; see the service's documentation for the current ones). If you go over, you get a 429. The workflow needs to account for this: either slow down or retry the request after a pause (with an increasing interval).

The agent knows the typical ways to handle rate limits and adds that handling, but check the specific limits against the service's documentation.

Real integrations: examples

Stripe (payments)

What it can do: accept card payments, create subscriptions, manage customers, send invoices, issue refunds.

Scenario: a workflow automatically invoices a client when a project is finished: the agent creates an invoice in Stripe through the API and sends a payment link.

# The agent writes this code for you
import stripe
stripe.api_key = os.environ["STRIPE_SECRET_KEY"]

invoice = stripe.Invoice.create(
    customer="cus_abc123",
    auto_advance=True,
)

Test mode: Stripe gives you test keys (sk_test_...) and a sandbox: you can test payments with test cards without real money.

Twilio (SMS and calls)

What it can do: send SMS, make calls, the WhatsApp Business API, phone number verification.

Scenario: a workflow monitors new leads. When a lead comes in from a VIP client (amount > $10,000), the agent texts the manager's phone.

from twilio.rest import Client
client = Client(os.environ["TWILIO_ACCOUNT_SID"], os.environ["TWILIO_AUTH_TOKEN"])

message = client.messages.create(
    body="New VIP lead: $15,000, get in touch today",
    from_="+1415xxxxxxx",
    to="+1212xxxxxxx"
)

SendGrid (email)

What it can do: send transactional emails (confirmations, notifications), marketing campaigns, email templates, open-rate analytics.

Scenario: after paying, the client automatically gets an email with instructions for accessing the course: the agent sends it through the SendGrid API.

The integration pattern: workflow + tools

🎨 Picture this: a workflow with tools is like an operations headquarters. The commander (the workflow) gives orders: "contact the supplier," "send the invoice," "notify the warehouse." Each specialist (tool) knows their task and their counterpart. The commander doesn't make the calls personally, they delegate.

In the WAT architecture (Workflow + Agent + Tools), API integrations live in the tools:

# workflows/invoice-on-completion.yaml
name: auto-invoice
description: Creates and sends an invoice when a project is marked as finished
steps:
  - action: get_project_details
  - action: create_stripe_invoice    # Stripe API
  - action: send_notification_email  # SendGrid API
  - action: send_sms_to_manager      # Twilio API
  - action: update_crm_status        # CRM API

Each action is a call to a separate tool. The tool knows how to talk to a specific API.

How Claude Code helps with APIs

🎨 Picture this: Claude Code with APIs is like a diplomat-interpreter. You say "I want to negotiate a supply deal." The interpreter knows the country's language, the protocol and the proper way to address people. The negotiations happen in the right language, and you get the result in yours.

Finding documentation: "find how to create a payment through the Stripe API for a one-time purchase without saving the card," and the agent finds the right endpoint in the documentation.

Writing code: the agent writes a tool function for a specific API call, with error handling and proper use of environment variables.

Debugging: if the API returns an error, the agent reads the response, understands the cause and fixes it.

Updating: if the API has changed (a new version), the agent finds what changed and updates the code.

Practice

Task: create an API endpoint and test it

1. Ask Claude Code: "Create a simple API endpoint in Express.js that accepts a POST request with name and email fields, validates that they aren't empty, and returns JSON confirming the data was received"

2. The agent will create a server.js file. Run it: node server.js

3. Test it with curl (the agent will help with the command):

curl -X POST http://localhost:3000/subscribe \
  -H "Content-Type: application/json" \
  -d '{"name": "Alex", "email": "[email protected]"}'

4. Try sending a request without an email and see how the error is handled

5. Extra credit: ask the agent to add an integration with a real service, for example "when an email comes in, add it to a Mailchimp list through the API" (you'll need a Mailchimp API key)

Tools and resources

• Postman: a graphical client for testing APIs, free
• Insomnia (insomnia.rest): an alternative to Postman, lighter
• OpenAPI Specification: the standard for describing REST APIs (Swagger). If a service provides an OpenAPI spec, Claude Code can read it and generate code automatically
• Stripe Dashboard: payment management, test keys
• SendGrid (sendgrid.com): has a free trial; see the site for terms and prices
• Twilio: a free trial number when you sign up
• httpbin.org: a test API for experiments (it returns whatever you send it)
• JSONPlaceholder (jsonplaceholder.typicode.com): a fake REST API for practice

Free plan terms change: for current prices and versions, see What's current.

Key takeaways

APIs aren't complicated, they're a standard. Once you understand that a request = URL + method + data, you understand the core of any API.

Keys go in .env, never in code: this isn't a recommendation, it's a rule with no exceptions. A single leaked key can cost thousands of dollars.

Claude Code turns you from "a person who can't program" into "a person who can integrate any service." That fundamentally changes the value you can offer clients.

Related lessons

• → MCP: extending Claude Code: MCP is a layer on top of APIs: instead of writing API calls by hand, an MCP server does it for you
• → MCP Builder: how to build your own MCP connector for any API

Next lesson

→ MCP: extending Claude Code: how to connect external tools