# Yago API Documentation for LLMs

## API Overview
**Name:** Yago API
**Version:** 1.0.0
**Base URL:** https://yago.cloud
**Description:** Yago is an Augmented Reality (AR) platform that facilitates the integration of AR into webshops, manages 3D assets, and powers AR viewers (Yago Scenes). The API handles asset management, team collaboration (Projects), analytics, and a 3D modeling ordering service.

## Authentication
**Methods:**
- **JWT (Bearer):** Primary method. Headers should include `Authorization: Bearer <token>`.
- **Session/Cookie:** Supported via `sessionid`.
- **Token Auth:** Supported via `Token <token>`.

## Core Concepts & Data Model

### 1. Projects
The top-level container for organization.
- **Function:** Groups users and models.
- **Key Attributes:** `name`, `slug` (for URLs), `gallery` (boolean to enable public AR gallery).
- **Settings:** Can toggle translations (DE, EN, FR, IT) and backlink URLs.

### 2. Models
The core 3D assets.
- **Hierarchy:** A Model belongs to a Project.
- **Files:**
  - `glb`: Android/Web compatible 3D file.
  - `usdz`: iOS compatible 3D file.
  - `image`: Preview image/thumbnail.
  - `source`: The original raw file (Blender/Maya).
- **Status Workflow:** `DRAFT` -> `READY` -> `ONLINE`.
- **Embedding:** Models have a `slug` used to generate embed codes or QR configurations.
- **Metadata:** Supports multi-language names (`name_de`, `name_en`) and descriptions.

### 3. Orders (Service Workflow)
A workflow to request 3D modeling services from the Yago team.
- **State Machine:**
  1. `PREPARING`: User adds reference images/dimensions.
  2. `ESTIMATING`: Submitted to Yago for price estimation.
  3. `READY_TO_PAY`: Price set, waiting for user payment.
  4. `IN_PROGRESS`: Yago team is modeling.
  5. `IN_REVIEW`: Model uploaded, user reviewing.
  6. `FINISHED`: Accepted and complete.
  - *Branch:* `RAGE_QUIT` (Cancelled).
- **Capabilities:** Users can comment on orders and request rework during the review phase.

## API Endpoints Guide

### Authentication & Users
- `POST /api/auth/login/`: Obtain JWT access/refresh tokens.
- `POST /api/auth/google/`: Login/Signup via Google ID token.
- `POST /api/auth/refresh/`: Refresh an expired access token.
- `GET /api/users/me/`: Get current user details.
- `POST /api/registration/`: Register a new account.

### Project Management
- `GET /api/projects/`: List all projects.
- `POST /api/projects/`: Create a project.
- `PUT /api/projects/{id}/image/`: Upload project gallery image (Max 30MB).
- `GET /api/memberships/`: Manage team members within a project.

### Model Management (CMS)
- `GET /api/models/`: List models (filterable by project).
- `POST /api/models/`: Create a model metadata entry.
- `PUT /api/models/{id}/`: Update model details (scaleable, vertical_placement, urls).
- **File Uploads:**
  - `PUT /api/models/{id}/glb/`: Upload GLB file.
  - `PUT /api/models/{id}/usdz/`: Upload USDZ file.
  - `PUT /api/models/{id}/image/`: Upload preview image.
- `GET /api/models/{slug}/embed/options/`: Retrieve configuration for the `<ar-button>` web component.

### Order Workflow (3D Service)
- `POST /api/orders/`: Create a new modeling order.
- `POST /api/orders/{order_id}/models/`: Add specific items (dimensions/refs) to an order.
- **State Transitions (Actions):**
  - `PATCH .../submit_to_estimation/`: Request price quote.
  - `PATCH .../submit_to_payment/`: (Admin/System) Set ready for payment.
  - `PATCH .../submit_to_progress/`: Payment confirmed, start work.
  - `PATCH .../submit_to_review/`: Work done, requesting user review.
  - `PATCH .../submit_to_rework/`: User requests changes.
  - `PATCH .../submit_to_finished/`: User accepts model.

### Customer & Billing
- `GET /api/customer/`: Get customer account details.
- `GET /api/customer/billing_address/`: Manage billing details.
- `GET /api/plans/`: List available pricing plans (quotas, SEO features, etc.).

### Analytics (Stats)
- `POST /api/stats/project/{id}/summary/`: Get aggregated stats (views, devices, countries).
- `POST /api/stats/project/{id}/chronic/`: Get time-series stats (timeline).
- **Metrics:** Track AR views, model views, browser types, and device types.

## Technical Constraints & Notes
- **File Size:** Uploads are generally limited to 30MB per file.
- **Content-Disposition:** Required header for file uploads (`attachment; filename=name.ext`).
- **Slugs:** Projects and Models use immutable slugs for public URLs.
- **Languages:** The system supports `de`, `en`, `fr`, `it` for customer-facing text.