What Is an API Endpoint? Definition, Anatomy, and a Real Example

An API endpoint is a specific address where an API receives a request and sends back a response. In most web APIs, an endpoint is an HTTP method plus a URL path, such as POST https://api.olostep.com/v1/scrapes.

The method says what you want to do. The URL says where the request goes. Together, they point to one job the API can perform.

API endpoints carry a large share of dynamic web traffic. The Cloudflare Radar 2025 Year in Review reports: "More than half of the dynamic traffic seen by Cloudflare is API related, and it continues to grow over time." That figure covers dynamic traffic on Cloudflare's network, not the whole internet.

API vs. Endpoint vs. Base URL vs. Route

Four terms get mixed up when people first read API docs. Each one names a different layer of the same request.

API vs. Endpoint

An API is the full contract between two programs. It contains every endpoint, plus the rules for authentication, request formats and response formats.

An endpoint is one entry point inside that API. Olostep, for example, is one API with separate endpoints for scraping a page, crawling a site, mapping URLs and answering questions.

Base URL, Path, and Full Request URL

The base URL is the shared root address for every endpoint in an API. For Olostep, the base URL is https://api.olostep.com.

The path is the part added after the base URL, such as /v1/scrapes. The full request URL joins the two: https://api.olostep.com/v1/scrapes.

A common setup mistake is pasting the full URL into a tool's "base URL" field. The tool then adds the path again, and requests go to /v1/scrapes/v1/scrapes, which returns an error.

Route vs. Endpoint

A route is a path pattern on the server, such as /users. An endpoint is a method combined with that route.

That means GET /users and POST /users are two different endpoints at the same URL. The first lists users, and the second creates one. The HTTP standard backs this view: "The request method token is the primary source of request semantics."

The Anatomy of an API Endpoint

Endpoint calls are built from the same set of parts. The table below breaks down a request to check the status of an Olostep batch job.

Put together, the request reads GET https://api.olostep.com/v1/batches/{batch_id}. A path parameter answers "which one?" A query parameter answers "which ones, and how many?"

HTTP Methods Tell the Endpoint What to Do

The HTTP method tells the endpoint which action to perform on a resource. Five methods cover most API work:

• GET: Reads data without changing it.
• POST: Creates something new or starts a job.
• PUT: Replaces a resource completely.
• PATCH: Updates part of a resource.
• DELETE: Removes a resource.

Two properties decide whether a call is safe to repeat. A safe method, like GET, does not change anything on the server. An idempotent method gives the same result whether you send it once or five times.

RFC 9110 HTTP Semantics states: "Of the request methods defined by this specification, PUT, DELETE, and safe request methods are idempotent." POST is not on that list, so retrying a POST after a timeout can create a duplicate job.

How an API Endpoint Works: A Real Request and Response

An endpoint works in a request-response cycle. Your code sends a request, the server checks it and does the work, and the server returns a status code with data.

Here is that cycle with Olostep's Scrapes endpoint, which fetches one web page and returns its content.

1. Send the request. Your code calls POST /v1/scrapes with your API key in the header and the target URL in the body.
2. Authenticate. The server reads the Authorization: Bearer <token> header and confirms the key is valid.
3. Do the job. The server fetches the page and converts it into the formats you asked for.
4. Return the response. The server sends back an HTTP status code and a JSON object.

Sample request:

curl -X POST "https://api.olostep.com/v1/scrapes" \
  -H "Authorization: Bearer $OLOSTEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url_to_scrape": "https://example.com",
    "formats": ["markdown"]
  }'

Sample response (shortened):

{
  "id": "scrape_abc123",
  "object": "scrape",
  "url_to_scrape": "https://example.com",
  "result": {
    "markdown_content": "# Example Domain\n\nThis domain is for use in illustrative examples...",
    "page_metadata": {
      "status_code": 200,
      "title": "Example Domain"
    }
  },
  "credits_consumed": 1
}

The object field confirms which endpoint answered. The result field holds the page content, and credits_consumed shows what the call cost. The ID and credit values above are illustrative.

Reading the Status Code

The status code is a three-digit number that tells you whether the request worked. Its first digit sets the class: 1xx informational, 2xx success, 3xx redirection, 4xx client error and 5xx server error.

A 429 response often includes a Retry-After header that says how long to wait. For retry patterns, see this guide to handling 429 rate-limit errors.

Synchronous vs. Asynchronous Endpoints

A synchronous endpoint returns the finished result in the same response. An asynchronous endpoint accepts the job, returns an ID right away, and gives you the result later.

Asynchronous endpoints exist because some jobs take longer than a single HTTP request should stay open. The asynchronous Batches endpoint shows the pattern:

1. Start the job. POST /v1/batches accepts a list of items, each with a url and a custom_id.
2. Get an ID. The response includes a batch id and a status of in_progress or completed.
3. Check progress. GET /v1/batches/{batch_id} returns the current status and the count of completed URLs.
4. Or get notified. Pass a webhook URL, and Olostep sends an HTTP POST to that URL when the batch completes. Failed webhook deliveries are retried up to 5 times over 30 minutes.

A webhook flips the direction of the call. Instead of your code calling the API, the API calls an endpoint you host.

Why One API Has Many Endpoints

Most REST APIs give each job its own endpoint, so every endpoint has one clear input and one predictable response shape. That makes requests easier to document, test and change.

Olostep follows this design. POST /v1/scrapes returns one page, the site mapping endpoint lists the URLs on a website, and the Crawls endpoint follows links across a site and retrieves the pages it finds.

GraphQL takes a different approach. A GraphQL API usually exposes a single endpoint, and the client describes the exact data it wants in the query.

REST remains the most common style. Postman's 2025 State of the API survey reports: "REST still dominates at 93%, but modern patterns are growing. Webhooks (50%), WebSockets (35%), and GraphQL (33%)…" These numbers show the share of survey respondents who use each style, not a share of all APIs.

API Endpoints and AI Agents

AI agents use API endpoints as tools. The agent reads the endpoint's description, decides when to call it, and uses the JSON response to plan its next step.

That makes endpoint design matter more. Clear names, predictable JSON and idempotent retries help software that calls endpoints without a person checking each request.

The Answers endpoint is one example: an agent sends a question and gets back a structured, source-grounded answer from the live web. Few developers design for this caller yet. Postman's 2025 survey found: "Only 24% of developers actively design APIs with AI agents in mind."

How to Keep API Endpoints Secure

Every public endpoint is an entry point into your system, so each one needs its own checks. The OWASP API Security Top 10 ranks Broken Object Level Authorization first and explains: "APIs tend to expose endpoints that handle object identifiers, creating a wide attack surface of Object Level Access Control issues."

Four practices cover the basics:

• Authenticate every request: Require an API key or Bearer token, and send it only over HTTPS.
• Check object-level access: Confirm the caller owns the specific ID they request, not just that they're logged in.
• Rate-limit traffic: Return 429 when a client sends too many requests.
• Keep an endpoint inventory: Track every endpoint and version so old ones don't stay exposed.

Never put API keys in front-end code or public repositories. Store them in environment variables or a secrets manager.

Frequently Asked Questions

What Is an Example of an API Endpoint?

POST https://api.olostep.com/v1/scrapes is an API endpoint. It takes a URL in the request body and returns that page's content as JSON.

What Is the Difference Between a REST API and an Endpoint?

A REST API is the whole set of rules and resources a service exposes over HTTP. An endpoint is one method-and-path pair inside that API, such as GET /v1/batches/{batch_id}.

Is a URL the Same as an Endpoint?

No, a URL is only the address. An endpoint is the address plus the HTTP method, so one URL can host several endpoints.

What Is the Difference Between a Resource and an Endpoint?

A resource is the data itself, such as a batch or a user. An endpoint is the address and method you use to read or change that resource.

Is a Webhook an API Endpoint?

Yes, a webhook is an endpoint you host so another service can send you data when an event happens. The direction is reversed: the API calls you instead of you calling the API.

How Do I Find an API's Endpoints?

Check the API's reference documentation, which lists each endpoint with its method, path, parameters and sample responses. Many APIs also publish an OpenAPI specification that lists every endpoint in one file.

Is an API Endpoint the Same as an Endpoint in Cybersecurity?

No, in cybersecurity an "endpoint" usually means a device such as a laptop or phone. An API endpoint is a network address on a server that accepts API requests.