What is an API, an endpoint and an API key?

An API is a defined interface that lets one program send requests to another and get structured responses back. An endpoint is one specific address within that API, such as the URL that accepts chat requests. An API key is a secret credential sent with each request to identify and authorize the caller.

What is an API, in plain terms?

An API, or application programming interface, is a published contract that says what requests a service accepts and what it returns. If you want software to use an AI model, the API is how your code talks to it.

A restaurant menu is a fair comparison. The menu lists what you can order and how to ask for it. You do not walk into the kitchen or need to know how the dish is made. You place an order in the expected form, and the kitchen sends back a plate. An API does the same for software: it lists the operations available, the exact shape of a valid request, and the shape of the reply. The analogy stops there, because unlike a waiter, an API will not guess what you meant. A request in the wrong shape is rejected.

For AI models, the operation you use most is "send these messages to this model and return its reply". Everything that makes AI apps work, from chat interfaces to coding agents, sits on top of requests like that.

What is an endpoint?

An endpoint is the full URL for one operation in an API. An API usually has several endpoints, each doing one job.

Gatewayz exposes three that matter for most builders:

Two terms often get mixed up here. The base URL is the shared prefix an SDK is configured with. The endpoint is the base URL plus the path for a specific operation. OpenAI-style SDKs take the base URL https://api.gatewayz.ai/v1 and append /chat/completions. Anthropic SDKs and Claude Code take the host https://api.gatewayz.ai and append /v1/messages. Getting this wrong by one path segment is a common first error, covered in Run Claude Code through Gatewayz.

What does an HTTP request to an AI model look like?

An HTTP request is a method, a URL, a set of headers and, for most AI calls, a JSON body. The model's reply comes back as an HTTP response with a status code, headers and a JSON body.

Here is each part, using a chat request as the example:

• Method. POST, because you are sending data for the server to act on. Reading the catalog uses GET.
• URL. The endpoint, for example https://api.gatewayz.ai/v1/chat/completions.
• Headers. Metadata about the request. The two you always need are Authorization, which carries your key, and Content-Type: application/json, which says the body is JSON.
• Body. The actual instruction: which model, which messages, and optional settings such as a maximum output length.

MDN's overview of HTTP is a good general reference if these terms are new.

A complete request with curl:

curl -s https://api.gatewayz.ai/v1/chat/completions \
  -H "Authorization: Bearer $GATEWAYZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5-mini",
    "messages": [
      {"role": "system", "content": "You answer in one sentence."},
      {"role": "user", "content": "What is an endpoint?"}
    ]
  }'

The key is read from an environment variable rather than typed into the command, which keeps it out of your shell history and out of any file you might share. The model field names a model id from the catalog. AI models and providers explains how those ids work and why dated snapshots matter.

A successful response has status 200 and a body shaped like this, trimmed to the fields you use most:

{
  "id": "chatcmpl-...",
  "model": "openai/gpt-5-mini",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "An endpoint is ..."},
      "finish_reason": "stop"
    }
  ],
  "usage": {"prompt_tokens": 24, "completion_tokens": 18, "total_tokens": 42}
}

The reply text lives at choices[0].message.content. The usage block reports input and output tokens, which is what the request is billed on.

What is the difference between Chat Completions and the Messages API?

Both formats send a list of messages to a model and return its reply, but they differ in path, header conventions, where the system prompt goes, which fields are required, and the shape of the response. Most tools are built for one or the other.

The OpenAI-compatible Chat Completions format started with OpenAI's API and has become a common interface that many tools and SDKs accept. The Anthropic Messages API is Anthropic's native format, used by the Anthropic SDKs and by Claude Code. The primary references are OpenAI's Chat Completions API reference and Anthropic's Messages API reference.

The same request in the Messages format through Gatewayz:

curl -s https://api.gatewayz.ai/v1/messages \
  -H "Authorization: Bearer $GATEWAYZ_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4-6",
    "max_tokens": 256,
    "system": "You answer in one sentence.",
    "messages": [
      {"role": "user", "content": "What is an endpoint?"}
    ]
  }'

And the shape of its reply:

{
  "id": "msg_...",
  "type": "message",
  "role": "assistant",
  "model": "anthropic/claude-sonnet-4-6",
  "content": [{"type": "text", "text": "An endpoint is ..."}],
  "stop_reason": "end_turn",
  "usage": {"input_tokens": 20, "output_tokens": 17}
}

Which format should you use?

Use the format your tool already speaks. If you are using an OpenAI SDK, a framework built around it, or a tool that asks for an "OpenAI base URL", use Chat Completions. If you are using an Anthropic SDK or Claude Code, use Messages, which keeps Anthropic-specific features such as cache_control in their native form. Prompt caching through a gateway covers why that matters for cost.

What is an API key, and why does one key matter?

An API key is a long random string that identifies your account on each request. The server checks it before doing any work, then records usage against the account it belongs to.

Without a gateway, calling models from several providers means holding a separate key for each one, with separate billing accounts, separate dashboards, and separate procedures for replacing a leaked key. Each additional key is another secret that can leak and another place a balance can run out.

With Gatewayz, one key authorizes requests to models from every provider in the catalog, billed from one prepaid balance. That has practical effects:

• One secret to protect. Your secret manager, CI settings and deployment config hold one credential instead of several.
• One place to replace it. If a key leaks, you delete it and create a new one in one place, instead of once per provider.
• Per-key limits. You can create a separate key per agent or environment and give each a request cap, set when the key is created or updated. When the cap is spent, that key returns 402 request_cap_exhausted while your other keys keep working. Spend ceilings for unattended agents goes deeper.

Keys are obtained at beta.gatewayz.ai.

How should you protect an API key?

Treat an API key exactly like a password to your account's spending. Anyone who has it can send requests that are billed to you.

A practical checklist:

1. Never commit keys to source control. Load them from environment variables or a secret manager. A key pushed to a public repository should be treated as compromised, even if the commit is deleted.
2. Keep keys server-side. Do not put a key in browser JavaScript, a mobile app bundle, or any code that ships to users. Anything shipped to a device can be extracted. Call the model from your backend instead.
3. Use one key per agent or environment. Separate keys for development, staging and production, and for each unattended agent, limit the damage from any single leak and make usage easier to read.
4. Set a request cap on each key. A cap bounds what a leaked or runaway key can spend.
5. Replace immediately on suspicion. If a key appears in a log, a screenshot, a chat message or a public commit, delete it and issue a new one first, and investigate second.

The OWASP Secrets Management Cheat Sheet is a thorough general reference on storing, distributing and rotating credentials. How Gatewayz keeps your API keys and data secure covers what happens on the Gatewayz side.

What do HTTP status codes mean for AI API requests?

A status code is a three-digit number on every response that tells the client the outcome class before it reads the body. The classes are defined in RFC 9110, the HTTP semantics standard: 2xx means success, 4xx means a problem with the request or the client, and 5xx means the server failed to handle a request that may have been valid. Within 4xx, 429 is the notable exception that says to slow down rather than change the request.

The most useful question for each failure is whether retrying the identical request could ever work. If not, the status is terminal. If so, it is retryable.

Error bodies share one shape, so code can branch on the code field rather than parsing prose:

{"error": {"message": "...", "type": "...", "code": "invalid_api_key"}}

For streamed responses, a failure partway through ends with an explicit error event rather than a silently cut-off stream. Streaming failures agents can detect explains why that matters, and Who reads the error? explains why getting the status class right is what keeps a typo from looking like an outage. MDN keeps a readable list of HTTP status codes for the codes not covered here.

Frequently asked questions

Is an API the same as an endpoint?

No. An API is the whole contract a service offers, covering every operation, request shape and response shape. An endpoint is one URL within that API for one operation, such as https://api.gatewayz.ai/v1/chat/completions for chat requests or https://api.gatewayz.ai/v1/models for the catalog.

Which endpoint should I use, Chat Completions or Messages?

Use the one your tool is built for. Code written with an OpenAI SDK, or a tool that asks for an OpenAI base URL, should use https://api.gatewayz.ai/v1/chat/completions with the base URL https://api.gatewayz.ai/v1. Code written with an Anthropic SDK, and Claude Code, should use https://api.gatewayz.ai/v1/messages with the host https://api.gatewayz.ai as the base URL.

Which header carries my Gatewayz key?

Send it as Authorization: Bearer <key> on both the Chat Completions and Messages endpoints. Claude Code does this when you set ANTHROPIC_AUTH_TOKEN to your key and ANTHROPIC_BASE_URL to https://api.gatewayz.ai.

Is it safe to put my API key in a frontend app?

No. Anything shipped to a browser or mobile device can be read by whoever runs it, and a key found there can be used to send requests billed to your account. Keep the key on a server you control, have your frontend call that server, and set a request cap on the key as a backstop.

Should my code retry a 402?

No. Both 402 codes are terminal until a person changes something: request_cap_exhausted needs the key's cap raised, and insufficient_credits needs the balance topped up. Retrying in a loop will only produce more 402 responses. Retry 429 and 5xx responses with backoff instead.

Related

• AI models and providers. What the model id in your request refers to.
• Your first Gatewayz API request. Put these pieces together in five minutes.
• Who reads the error?. Why status codes are control flow for agents.
• How Gatewayz keeps your API keys and data secure. What happens to your key on the server side.
• Run Claude Code through Gatewayz. The Messages format in practice.