Core concepts

Endpoints

Endpoints define the URLs your application calls and the responses Forge API returns. Each endpoint belongs to a project and combines an HTTP method, path, status code, JSON body and optional configuration.

Estimated time: 6 minutesDifficulty: Beginner

Every endpoint belongs to a project

The project supplies the public project key used in the URL. The endpoint supplies the HTTP method, path and response configuration.

Endpoint structure

A public endpoint URL contains the Forge API domain, project key and endpoint path.

URL

https://apis.getforgeapi.com/abc12/products

API domain

https://apis.getforgeapi.com

Project key

abc12

Endpoint path

/products

Example keys are placeholders

Replace example project keys such as abc12 with the real public key shown in your project dashboard.

Create an endpoint

Add an endpoint from inside an existing project.

1
Open a project from the Forge API dashboard.
2
Select New endpoint.
3
Choose an HTTP method and enter a path.
4
Add a valid JSON response body.
5
Configure the status code, headers and optional response delay.
6
Save the endpoint and copy its public URL.

HTTP methods

The method determines which type of request matches the endpoint.

GET

Retrieve mock data such as products, users or orders.

POST

Simulate creating data, submitting forms or logging in.

PUT

Simulate replacing an existing resource.

PATCH

Simulate partially updating an existing resource.

DELETE

Simulate deleting a resource.

HEAD

Return response headers without returning the response body.

Method and path are matched together

You can create different endpoints using the same path when the HTTP methods are different. For example, GET /products and POST /products are separate endpoints.

Endpoint paths

The path identifies the resource or action represented by the endpoint.

text

/products
/products/featured
/products/1
/users/profile
/orders/latest
/auth/login

Forge API normalises endpoint paths so they begin with a forward slash. Trailing slashes are removed from paths longer than the root path.

Do not include query parameters

Configure only the route path. Do not include values such as ?page=2 or URL fragments such as #section in the endpoint path.

JSON response body

The response body is the JSON returned when the endpoint is called.

You can return JSON objects, arrays, nested values, booleans, numbers and null values.

product.jsonJSON

{
  "id": 1,
  "name": "Polo Shirt",
  "size": "M",
  "price": 10,
  "in_stock": true
}

Forge API validates the JSON before saving it. Invalid JSON must be corrected before the endpoint can be created or updated.

Match your planned production API

Use the same field names, object shapes and data types your real backend is expected to return. This reduces frontend changes later.

Response status codes

Choose the HTTP status code returned with the response.

200OKA successful request returning data.

201CreatedA resource was successfully created.

204No ContentThe request succeeded without a response body.

400Bad RequestThe request was invalid.

401UnauthorizedAuthentication or a required secret is missing.

404Not FoundThe requested resource could not be found.

500Internal Server ErrorSimulate a server-side failure.

Status codes are useful for testing success, validation, empty, unauthorized and failure states in your frontend.

validation-error.jsonJSON

{
  "success": false,
  "error": {
    "code": "validation_failed",
    "message": "The email address is required."
  }
}

Response headers

Add custom headers that Forge API should return with the endpoint response.

Header name

Content-Type

Header value

application/json; charset=utf-8

A new endpoint starts with a JSON content type by default. You may add additional response headers when your application needs to test custom behaviour.

Cache-related headers
Custom application metadata
API version headers
Testing-specific headers

Some response headers are blocked

Forge API does not forward unsafe transport-level headers such as Content-Length, Connection or Set-Cookie.

Required request headers

Paid plans can require callers to provide secret header values before receiving the mock response.

Request-header protection can be configured at project level, endpoint level or both.

Header name

x-api-key

Required value

your-secret-value

Call the endpoint with the configured header:

bash

curl \
  -H "x-api-key: your-secret-value" \
  https://apis.getforgeapi.com/abc12/products

Requests with a missing or incorrect value are rejected before the configured JSON response is returned.

Project and endpoint protection are combined

When a project and an endpoint both define required headers, callers must provide all required project headers and all required endpoint headers.

Shared secrets are not full authentication

Request-header protection is useful for test environments, internal tools and controlled integrations. Do not treat it as a replacement for OAuth, user sessions or a production authorization system.

Required request headers are available on supported paid plans. Compare plans.

Response delays

Simulate slower backend responses to test loading states and timeout behaviour.

Supported paid plans can configure a response delay in milliseconds. Forge API waits for the configured duration before returning the endpoint response.

Delay

1500 milliseconds

Result

The response is returned after approximately 1.5 seconds.

bash

curl \
  -i \
  https://apis.getforgeapi.com/abc12/slow-response

Response-delay limits depend on the account plan. Forge API applies the maximum delay permitted by the active plan.

Test loading indicators

Use a short delay to confirm that spinners, skeleton screens, disabled buttons and timeout messages behave as expected.

Activate or deactivate an endpoint

Temporarily stop an endpoint without deleting its configuration.

Active endpoints return their configured response. Inactive endpoints remain saved in the dashboard but are unavailable to public callers.

Active

The endpoint can be called through its public URL.

Inactive

The endpoint remains saved but public requests are rejected.

Useful during development

Deactivate an endpoint when you want to preserve its response and settings without allowing applications to continue calling it.

Edit an endpoint

Update an endpoint without creating a new public URL.

Open the endpoint from your project dashboard to update:

HTTP method
Endpoint path
Response status code
JSON response body
Response headers
Required request headers
Response delay
Active or inactive state

Changing the path changes the URL

Applications calling the previous path will no longer reach the endpoint after the path is changed. Update any connected frontend, mobile application or test suite.

Duplicate endpoints

A project cannot contain two endpoints with the same method and path.

The following pair is not allowed inside the same project:

text

GET /products
GET /products

Different methods may use the same path:

text

GET /products
POST /products
DELETE /products

Delete an endpoint

Remove an endpoint permanently when it is no longer required.

Once deleted, the endpoint URL returns a not-found response. Save any JSON or configuration you may need before deleting it.

Deletion cannot be undone

Consider deactivating the endpoint first when you may need to restore it later.

Endpoint limits

Endpoint and response-size limits depend on your Forge API plan.

Plan limits may control:

Endpoints allowed per project
Maximum JSON response size
Maximum response delay
Request-header protection availability
Monthly request allowance

View API limits Compare plans

Create a mock endpoint

Choose a method, define a response and start using a hosted API URL from your application.

Open projects Learn how to call endpoints