# API Basics

This page introduces the foundational structure of the DevPayr API. Before interacting with any endpoint, it’s important to understand **where requests are sent**, **how versions are handled**, and **how requests and responses are structured**.

These concepts apply uniformly across all DevPayr API endpoints.

### Base URL

All DevPayr API requests are made against the following base URL:

```
https://api.devpayr.dev/api/v1/
```

This base URL consists of three parts:

* **`api.devpayr.dev`**\
  The public API host for all third-party and SDK-driven requests.
* **`/api`**\
  Indicates that the request is being made to DevPayr’s programmatic API layer.
* **`/v1`**\
  The current stable API version.

All endpoint paths shown throughout this documentation are **relative to `/api/v1`**.\
For example, an endpoint documented as:

```
GET /projects
```

Should be called as:

```
GET https://api.devpayr.dev/api/v1/projects
```

### Versioning Strategy

DevPayr uses **explicit, URL-based versioning**.

* Each major API version is represented by a version segment in the URL.
* The current version is **v1**.
* Future versions (for example, `v2`) will be released under a new path without breaking existing integrations.

#### Why versioning matters

* Breaking changes are introduced **only** in new versions.
* Existing integrations remain stable until you intentionally upgrade.
* You can safely test newer versions in parallel while keeping production traffic on an older version.

When a new version is released, its behavior, requirements, and changes will be documented separately.

### API Root (Health & Connectivity Check)

The API root endpoint can be used to verify basic connectivity to the DevPayr API.

```
GET /
```

#### Example Response

```json
{
  "status": "ok",
  "message": "Welcome to DevPayr api endpoint"
}
```

#### Notes

* This endpoint does not perform authentication.
* It is intended strictly for:
  * connectivity checks
  * basic uptime validation
* The endpoint is rate-limited and should not be used as a monitoring or heartbeat endpoint in production.

### Request Format

DevPayr is designed as a **JSON-first API**.

#### Requests

* Request bodies must be sent as JSON where applicable.
* Parameters are accepted through:
  * URL path segments
  * query strings
  * JSON request bodies

Requests that do not conform to the expected format may be rejected or fail validation.

### Response Format

All API responses are returned in **JSON format**.

A typical successful response contains:

* the requested data (or confirmation message)
* appropriate HTTP status codes

Error responses return a JSON object containing a descriptive `message` field.

Example:

```json
{
  "message": "Resource not found."
}
```

Error handling and status codes are covered in detail later in this guide.

### Headers

#### Recommended Headers

| Header                           | When to use        | Description                               |
| -------------------------------- | ------------------ | ----------------------------------------- |
| `Accept: application/json`       | Always             | Ensures responses are returned in JSON    |
| `Content-Type: application/json` | POST / PUT / PATCH | Required when sending a JSON request body |

Failing to include the appropriate headers may result in:

* rejected requests
* unexpected error responses
* content negotiation failures

### HTTP Methods & Semantics

DevPayr follows standard RESTful HTTP semantics.

| Method   | Description                           |
| -------- | ------------------------------------- |
| `GET`    | Retrieve one or more resources        |
| `POST`   | Create a new resource                 |
| `PATCH`  | Partially update an existing resource |
| `PUT`    | Fully replace an existing resource    |
| `DELETE` | Remove a resource                     |

Using the correct HTTP method is required; unsupported methods will return an error.

### Pagination & Filtering

Some list endpoints support pagination and filtering.

* Pagination parameters (such as `page`, `per_page`) may be available depending on the endpoint.
* Filtering and search capabilities vary by resource.

Each endpoint documents its supported query parameters individually.

### Time & Date Handling

* All timestamps are returned in **ISO-8601 format**.
* Times are expressed in **UTC**.

Example:

```json
"created_at": "2025-12-01T10:12:00Z"
```

### What’s Next?

Now that you understand:

* where the API lives
* how versioning works
* how requests and responses are structured

the next step is learning **how DevPayr authenticates requests and identifies callers**.