# Overview

The v2 API is our project-scoped API: a single, consistent interface for working with YGO's products on behalf of a project. You authenticate as a project, call the products enabled for it, and get back predictable, ready-to-use results.

## Products

The API is organized into products, each served under its own path. You use the ones enabled for your project.

- **Content Enrichment** -- available now. Retrieve enriched hotels, manage the templates that drive your marketing texts, and generate localized descriptions on demand.

---

## A Single, Consistent API

Every v2 endpoint follows the same conventions, so once you have integrated one call you understand them all.

- **One base URL** -- All requests go to `https://api.ygo.ai`.
- **RPC-style paths** -- Each operation has its own path under `/v2/project/{product}/{operation}`, for example `/v2/project/content/getEnrichedHotel`. The path names the product and the action you want to perform.
- **POST for everything** -- All endpoints use `POST`. Parameters travel in a JSON request body rather than in the URL or query string, which keeps requests uniform and easy to construct.
- **JSON in, JSON out** -- Send and receive `application/json`.

---

## The Response Envelope

Every successful response wraps its payload in a single top-level `Data` field. This is consistent across all endpoints, whether you are fetching one hotel or a list of many.

```json
{
  "Data": { }
}
```

List endpoints return an array in `Data` alongside a `Pagination` object describing the result set:

```json
{
  "Data": [],
  "Pagination": { "Total": 1234, "Limit": 50, "Offset": 0 }
}
```

Errors replace `Data` with an `Error` object. See [Errors and Rate Limits](https://docs.ygo.ai/guides/errors-and-limits.md) for the full structure.

> **Info**
>
> **Check for field presence**
>
> Empty fields are omitted to keep payloads compact. Read responses by checking whether a field is present rather than assuming every field is always returned.

---

## Data Conventions

A few conventions hold across the whole API. Knowing them up front makes every response easy to parse.

- **PascalCase keys** -- Every JSON field uses PascalCase, for example `GlobalHotelID`, `Name`, and `Pagination`.
- **UUIDv7 identifiers** -- System-generated identifiers are UUIDv7 values such as `0192fb17-5dc6-7abc-8def-123456789abc`. They are time-ordered, so newer ids sort after older ones.
- **RFC 3339 dates** -- All timestamps use RFC 3339, for example `2026-02-02T10:30:00Z`.

Need help? Reach our integration team at `integrations@ygo.ai`.
