---
title: "Add a drawing document (from a URL, or prepare a direct upload)"
method: POST
path: "/documents"
tags: ["Documents"]
---

# Add a drawing document (from a URL, or prepare a direct upload)

`POST /documents`

## Request

- Base URL: `https://api.aginera.ai/partner/v1`
- URL: `https://api.aginera.ai/partner/v1/documents`
- Auth: OAuth 2 (authorization code, authorization URL `https://auth.aginera.ai/oauth/authorize`, token URL `https://auth.aginera.ai/oauth/token`; client credentials, token URL `https://login.microsoftonline.com/65f567a9-6e6a-4f81-863c-aea4ece1f8eb/oauth2/v2.0/token`, scopes: `documents:write`)

source.type = "url": Aginera fetches the file (HTTPS, ≤ 50 MB) and returns 202 with status "ingesting". source.type = "upload": returns 201 with a 15-minute upload URL; PUT the bytes, then call /documents/{id}/complete. Supported: PDF, DWG, DXF, PNG, JPEG.

## Headers

- `Idempotency-Key` string: Replays within 24 hours return the original response.

## Request body

- DocumentCreate
  - `project_id` string, required
  - `filename` string, required
  - `source` union, required
    - object
      - `type` 'url', required
      - `url` string, uri, required
    - object
      - `type` 'upload', required
      - `size_bytes` integer
      - `content_type` 'application/pdf' | 'image/vnd.dwg' | 'application/dxf' | 'image/png' | 'image/jpeg'
  - `kind` 'drawing' | 'specification' | 'schedule'
  - `discipline_hint` 'electrical' | 'mechanical' | 'plumbing' | 'fire_protection' | 'process' | 'structural' | 'multi_discipline'
  - `external_ref` string: Your own identifier for this resource; unique per tenant.
  - `metadata` Metadata

## Response `201`

OK

- union
  - DocumentWithUpload
    - `document` Document, required
      - `id` string, required
      - `project_id` string, required
      - `filename` string, required
      - `kind` 'drawing' | 'specification' | 'schedule', required
      - `status` 'awaiting_upload' | 'ingesting' | 'ready' | 'failed', required
      - `external_ref` string, nullable, required
      - `page_count` integer, nullable, required
      - `pages` DocumentPage[]
        - `number` integer, required
        - `sheet_number` string, nullable, required
        - `sheet_title` string, nullable, required
        - `has_text` boolean, required
        - `rotation` integer, required
        - `size_pt` object, required
          - `width` number, required
          - `height` number, required
        - `disciplines_detected` Trade[]
      - `size_bytes` integer, nullable, required
      - `failure` Failure
        - `code` 'document_unreadable' | 'unsupported_content' | 'no_pages_selected' | 'capacity' | 'cancelled' | 'internal', required
        - `message` string, required
      - `metadata` object, required
      - `created_at` string, date-time, required
      - `ready_at` string, date-time, nullable, required
      - `retain_until` string, date-time, nullable, required
    - `upload` object, required
      - `url` string, uri, required
      - `method` 'PUT', required
      - `headers` object, required
      - `expires_at` string, date-time, required
  - Document
    - `id` string, required
    - `project_id` string, required
    - `filename` string, required
    - `kind` 'drawing' | 'specification' | 'schedule', required
    - `status` 'awaiting_upload' | 'ingesting' | 'ready' | 'failed', required
    - `external_ref` string, nullable, required
    - `page_count` integer, nullable, required
    - `pages` DocumentPage[]
      - `number` integer, required
      - `sheet_number` string, nullable, required
      - `sheet_title` string, nullable, required
      - `has_text` boolean, required
      - `rotation` integer, required
      - `size_pt` object, required
        - `width` number, required
        - `height` number, required
      - `disciplines_detected` Trade[]
    - `size_bytes` integer, nullable, required
    - `failure` Failure
      - `code` 'document_unreadable' | 'unsupported_content' | 'no_pages_selected' | 'capacity' | 'cancelled' | 'internal', required
      - `message` string, required
    - `metadata` object, required
    - `created_at` string, date-time, required
    - `ready_at` string, date-time, nullable, required
    - `retain_until` string, date-time, nullable, required

## Other responses

- `202`: Ingesting from URL
- `default`: Error (RFC 7807)

---

[API](https://skmtc.dev/aginera/apis/aginera-takeoff-estimation-api.md) · [All operations](https://skmtc.dev/aginera/apis/aginera-takeoff-estimation-api/llms.txt) · [OpenAPI document](https://skmtc.dev/aginera/apis/aginera-takeoff-estimation-api/revisions/39115958da1e?raw)