> ## Documentation Index
> Fetch the complete documentation index at: https://veryfront.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Requests and responses

> Construct requests and handle responses, pagination, errors, and retries.

The base URL is `https://api.veryfront.com`. Each endpoint defines its parameters, content types, and response schema.

## Base URL and paths

Combine the base URL with an endpoint path:

```http title="request.http" theme={null}
GET https://api.veryfront.com/runs/event-types
```

Replace placeholders such as `{run_id}` with the requested identifier. `{project_reference}` accepts a project ID or slug; some endpoint contracts also support domain references. Conversation endpoints use either `{id}` or `{conversation_id}` for the conversation ID.

URL-encode parameter values when required by the endpoint. For example, the file APIs document encoded paths such as `pages%2Findex.mdx`.

## Request parameters

Path parameters identify resources. Query parameters select, filter, or paginate results. Headers supply credentials and other request metadata.

For example, this request lists up to 20 projects visible to the caller. Set `VERYFRONT_API_KEY` to an authorized API key before running it:

```bash title="request.sh" theme={null}
curl 'https://api.veryfront.com/projects?limit=20' \
  --header "Authorization: Bearer $VERYFRONT_API_KEY" \
  --header 'Accept: application/json'
```

See [List projects](/docs/cloud/rest/api-reference/projects/list-projects) for supported filters and response fields. See [Authentication](/docs/cloud/rest/authentication) for credential options and access requirements.

## Request bodies

For JSON request bodies, send `Content-Type: application/json`. Use the endpoint’s **Request body** section for required fields, supported variants, and validation constraints.

Required fields and nullable fields are different: a required field must be present, while a nullable field may accept `null`. The endpoint schema defines both conditions.

For file uploads and provider proxy requests, use the content type and body format specified by the endpoint.

## Responses and errors

Each endpoint lists its HTTP status codes, response content types, and response schema.

A run-creation response can acknowledge work before it finishes. Use the returned run ID with the [run endpoints](/docs/cloud/rest/apis/execution-api#runs) to inspect status, events, and output.

For failures, inspect the HTTP status and documented error body. The [error type catalog](/docs/cloud/rest/apis/api-discovery-and-metadata#error-metadata) describes published error types. An error response may contain additional endpoint-specific details.

## Error metadata

For endpoints that return `application/problem+json`, the error type URI identifies the failure category. The response can also include a status, title, detail, and request-specific information. Use the [error type catalog](/docs/cloud/rest/apis/api-discovery-and-metadata#error-metadata) to interpret the published type; keep endpoint-specific validation details when reporting a failed request.

| Status | Client response |
| - | - |
| 400 | Inspect validation details and correct the request before retrying. |
| 401 | Check the credential and the endpoint's accepted authentication method. |
| 403 | Check credential scope and resource permissions. |
| 409 | Read the current resource state before retrying a conflicting write. |
| 429 | Follow the documented rate-limit and retry response for the endpoint. |

## Pagination and filters

To request another page, pass the returned cursor using the endpoint’s documented pagination parameter.

Keep filters and ordering unchanged between pages. Cursor fields, page sizes, and response formats vary by endpoint.

For example, `GET /projects` returns its next cursor in `page_info.next`. If it is not null, send it as the next request's `cursor` value:

```bash title="next-page.sh" theme={null}
curl --get 'https://api.veryfront.com/projects' \
  --header "Authorization: Bearer $VERYFRONT_API_KEY" \
  --data-urlencode 'limit=20' \
  --data-urlencode "cursor=$NEXT_CURSOR"
```

Set `NEXT_CURSOR` to the exact returned cursor. A null next cursor marks the end of this result set.

## Retries and concurrent updates

Before retrying a write, check whether the endpoint supports idempotency keys or another retry mechanism.

For conditional updates, supply the documented revision or precondition header. Handling a stale revision can require reading the resource again before submitting another update.

## Streaming responses

Run streams use server-sent events (SSE) over HTTP. Each stream endpoint specifies its reconnection and replay behavior. See [SSE run streams](/docs/cloud/rest/protocols#sse-run-streams) for entry points.

[Back to REST API reference](/docs/cloud/rest)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.