# 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**.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://devpayr.gitbook.io/devpayr-docs/api-reference/getting-started/api-basics.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.