Uhuu Docs

Appearance

Uhuu API ​

The Uhuu API enables teams to generate, manage, and retrieve dynamic documents from templates with authenticated requests.

Base URL:

bash
https://api.uhuu.io/v1

All responses are JSON and require HTTPS.

Documentation & Tools ​


Authorization ​

Create API tokens ​

Generate tokens from Team Settings → API Tokens inside app.uhuu.io. Ensure the token has the read scope for GETs and create for POSTs.

Send tokens ​

Every request must include a bearer token:

bash
Authorization: Bearer <token>
Accept: application/json
Content-Type: application/json

Request patterns ​

  • HTTP verbs: GET retrieves resources, POST triggers template renders or integration fetches. PUT/DELETE are currently not exposed.
  • Errors: Standard HTTP codes (400 validation, 401 auth, 403 permission, 404 missing resource, 429 throttling, 5xx service). Responses carry a message and status field when applicable.
  • fields filtering: Templates and Documents accept fields query params (comma-separated) to limit payloads, e.g. GET /documents/{id}?fields=status,pdf_url or fields=data to request heavy payloads only when needed.

Endpoint overview ​

MethodPathPurpose
GET/teamInspect the authenticated team, features, and workspaces.
GET/workspaces/{workspace_id}Retrieve workspace metadata plus attached templates.
GET/templates/{template_id}Fetch template configuration. Supports fields.
POST/templates/{template_id}Generate a document (optionally with input payload).
GET/templates/{template_id}/documentsList rendered documents for a template.
POST/templates/{template_id}/integrationPull integration data (e.g., CRM record) before rendering.
GET/documents/{document_id}Retrieve document status, URLs, and optional data via fields.

Endpoint details ​

Team ​

bash
GET /team

Returns the team profile and workspaces associated with the token.

json
{
  "id": 54,
  "name": "Developer Team",
  "features": {
    "uhuu-ai": true
  },
  "workspaces": [
    { "id": 63, "name": "Default Workspace" }
  ]
}

Workspace ​

bash
GET /workspaces/{workspace_id}

Provides workspace metadata (IDs, timestamps) and a summary of templates to help you discover available assets.

json
{
  "id": 6,
  "name": "Default Workspace",
  "team_id": 6,
  "created_at": "2021-09-29T15:16:41.000000Z",
  "updated_at": "2021-09-29T15:16:41.000000Z",
  "templates": [
    { "id": 1168, "name": "Direct Mail", "description": "Direct Mail" }
  ]
}

Template ​

bash
GET /templates/{template_id}?fields=integration,base_data,settings,remote_url

Returns template configuration, base data, integration bindings, and optional fields controlled by the fields query parameter.

json
{
  "id": 872,
  "name": "Direct Mail",
  "workspace_id": 63,
  "integration_bind": "user",
  "remote_url": "https://starter.uhuu.io/direct-mail/",
  "base_data": {
    "user": {
      "id": 2,
      "company": "Alpine Innovations",
      "first_name": "Mia",
      "last_name": "Keller"
    },
    "qr_url": "https://uhuu.io?workshop=true"
  },
  "settings": {
    "format": "A4",
    "layout": "portrait"
  },
  "updated_at": "2025-11-10T17:13:32.000000Z"
}

Generate document from template ​

bash
POST /templates/{template_id}

Send optional payload (e.g., { "id": "3" } for an integration-bound template). Successful requests return a document_id you can poll via /documents/{document_id}.

json
{
  "id": "bG9jYWxfdGVhbV81NCt0ZW1wbGF0ZV84NzJfZG9jdW1lbnRfNjkxMjFjNDcwMzQ4OQ==",
  "status": "rendering",
  "created_at": "2025-11-11T22:28:56.000000Z"
}

Template documents list ​

bash
GET /templates/{template_id}/documents

Lists recent renders for a template, including timestamps and duration metrics.

json
[
  {
    "id": "bG9jYWxfdGVhbV81NCt0ZW1wbGF0ZV84NzJfZG9jdW1lbnRfNjkxM2I4YTg2MjhmOQ==",
    "status": "ready",
    "url": "https://uhuuio.s3.eu-west-1.amazonaws.com/.../2025-11-11-2228.pdf",
    "created_at": "2025-11-11T22:28:56.000000Z",
    "rendered_at": "2025-11-11T22:29:00.125000Z",
    "duration": 3443
  }
]

Template integration data ​

bash
POST /templates/{template_id}/integration

Use when a template relies on remote data (e.g., CRM or ERP). Provide an identifier and receive the hydrated dataset that will be merged during rendering.

json
{
  "user": {
    "id": 3,
    "company": "Matterhorn Solutions",
    "first_name": "Noah",
    "last_name": "Schneider",
    "city": "Bern"
  },
  "qr_url": "https://uhuu.io?workshop=true",
  "message": "Dear {name}, ..."
}

Document ​

GET /documents/{document_id}

Retrieves render status, download URLs, timestamps, and optional data when requested.

json
{
    "id": "bG9jYWxfdGVhbV81NCt0ZW1wbGF0ZV84NzJfZG9jdW1lbnRfNjkxM2I4YTg2MjhmOQ==",
    "status": "ready",
    "url": "https://uhuuio.s3.eu-west-1.amazonaws.com/uhuu/local/team/54/template/872/document/6913b8a8628f9/2025-11-11-2228.pdf",
    "created_at": "2025-11-11T22:28:56.000000Z",
    "rendered_at": "2025-11-11T22:29:00.125000Z",
    "started_at": 1762900136682,
    "ended_at": 1762900140125,
    "duration": 3443
}

Add fields=data to include the full document payload:

json
{
  "data": {
    "user": {
      "id": 2,
      "first_name": "Mia",
      "last_name": "Keller",
      "company": "Alpine Innovations"
    },
    "qr_url": "https://uhuu.io?workshop=true"
  }
}

Error handling ​

The API returns RFC 9110-compliant codes plus a JSON body:

json
{
    "error": "Request body must be valid JSON. Error: Syntax error"
}

Retry guidance or throttling information is provided via HTTP headers (e.g., 429 with Retry-After). Always validate payloads to avoid 400 responses and confirm permissions for protected workspaces or templates to avoid 403 errors.