Aginera CAD API

openapi: 3.2.0
info:
  title: Aginera Ai CAD API
  version: 1.0.0-rc.1
  contact:
    name: Aginera Developer Support
    email: developers@aginera.ai
    url: https://aginera.ai/docs/developer
  license:
    name: Proprietary — Aginera Developer Platform Terms
    url: https://aginera.ai/legal/developer-terms
  termsOfService: https://aginera.ai/legal/developer-terms
  description: 'Operations tagged CAD across 3 of this provider''s published API definitions: aginera-ai-openapi.json, aginera-openapi.json, aginera-openapi.yaml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.aginera.ai/partner/v1
  description: Production and sandbox (environment is per credential)
security:
- oauth2: []
tags:
- name: CAD
  description: PDF→CAD conversion — converting and viewing are free; the DXF/DWG download is a one-time purchase per document on free accounts; the website's own pricing, on the user's account.
paths:
  /documents/{document_id}/cad:
    get:
      operationId: documents.cad.get
      summary: Can this PDF be converted to CAD, and what does it cost this user?
      description: 'Checks a ready PDF document (vector linework, or a scan that traces) and returns the website''s own pricing for this user: Converting and viewing are free; downloading the DXF or DWG (clean, every sheet) is a one-time purchase per document on free accounts (or credits for paying customers); paid plans are not charged. Converts and charges nothing. Requires a delegated (user) token — a service credential gets consent_required.'
      tags:
      - CAD
      security:
      - oauth2:
        - cad:convert
      x-aginera-cut: core
      parameters:
      - schema:
          $ref: '#/components/schemas/DocumentId'
        required: true
        name: document_id
        in: path
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CadStatus'
        default:
          description: Error (RFC 7807)
          content:
            application/problem+json:
              schema:
                type: object
                properties: {}
                $ref: '#/components/schemas/Problem'
    servers:
    - url: https://api.aginera.ai/partner/v1
      description: Production and sandbox (environment is per credential)
  /documents/{document_id}/cad-files:
    post:
      operationId: documents.cad.files.create
      summary: Convert a PDF to DXF/DWG and get a time-limited download link (or the price)
      description: 'Converts (up to ~3 minutes for large sets; cached afterwards) and returns status "ready" with a 60-minute download link, or status "purchase_required" with the price when the file is the $2 cad_dwg purchase (DWG, or any file over 50 MB, on a free account). Without `pay` nothing is charged or created. `pay: "credits"` pays from the user''s credit balance (paying customers) and returns the file; `pay: "checkout"` returns a Stripe checkout_url the user completes in their browser. Only send `pay` after the user has agreed to the price.'
      tags:
      - CAD
      security:
      - oauth2:
        - cad:convert
      x-aginera-cut: core
      parameters:
      - schema:
          $ref: '#/components/schemas/DocumentId'
        required: true
        name: document_id
        in: path
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CadFileCreate'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CadFileResult'
        default:
          description: Error (RFC 7807)
          content:
            application/problem+json:
              schema:
                type: object
                properties: {}
                $ref: '#/components/schemas/Problem'
    servers:
    - url: https://api.aginera.ai/partner/v1
      description: Production and sandbox (environment is per credential)
components:
  schemas:
    CadFileCreate:
      type: object
      properties:
        format:
          allOf:
          - $ref: '#/components/schemas/CadFormat'
          - default: dxf
        pay:
          $ref: '#/components/schemas/CadPay'
      additionalProperties: false
    DocumentId:
      type: string
      pattern: ^doc_[0-9A-Za-z]{22}$
      example: doc_4kR9sT2vWx7yZa1bCd3eFg
    CadStatus:
      type: object
      properties:
        document_id:
          $ref: '#/components/schemas/DocumentId'
        filename:
          type: string
        convertible:
          type: boolean
          description: Whether Aginera can turn this PDF into CAD (vector linework, or a scan that traced to linework).
        reason:
          type:
          - string
          - 'null'
          description: 'Why not, when convertible is false: not_pdf, raster_or_unreadable, no_vector_linework.'
        page_count:
          type:
          - integer
          - 'null'
        scan_traced:
          type: boolean
        trade_hint:
          type:
          - object
          - 'null'
          properties:
            trade:
              type:
              - string
              - 'null'
            label:
              type:
              - string
              - 'null'
            confidence:
              type: number
          required:
          - trade
          - label
          - confidence
        access:
          type: string
          enum:
          - purchased
          - unlocked
          - free
          description: purchased = the $2 CAD file was bought for this document; unlocked = a paid plan (no gate); free = free tier (viewing is free; downloading the DXF or DWG needs the purchase).
        paid:
          type: boolean
          description: The cad_dwg purchase exists for this document.
        pricing:
          type: object
          properties:
            mode:
              type: string
              enum:
              - download_paid
              - dwg_paid
              - first_sheet_free
            dxf:
              type: object
              properties:
                price_usd:
                  type: number
                watermarked:
                  type: boolean
                note:
                  type: string
              required:
              - price_usd
              - watermarked
              - note
            dwg:
              type: object
              properties:
                usd_cents:
                  type: integer
                price_usd:
                  type: number
                credits:
                  type: integer
                purchase_required:
                  type: boolean
                note:
                  type: string
              required:
              - usd_cents
              - price_usd
              - credits
              - purchase_required
              - note
            local_currency_note:
              type: string
          required:
          - mode
          - dxf
          - dwg
          - local_currency_note
        size:
          type: object
          properties:
            min_dxf_mb:
              type:
              - number
              - 'null'
            free_size_exceeded:
              type: boolean
          required:
          - min_dxf_mb
          - free_size_exceeded
        next_step:
          type: string
      required:
      - document_id
      - filename
      - convertible
      - reason
      - page_count
      - scan_traced
      - trade_hint
      - access
      - paid
      - pricing
      - size
      - next_step
    CadPay:
      type: string
      enum:
      - credits
      - checkout
      description: 'Only when the user has said yes to paying: "credits" pays the $2 from their credit balance (paying customers), "checkout" returns a Stripe link the user completes. Omit to only learn the price.'
    Problem:
      type: object
      properties:
        type:
          type: string
        title:
          type: string
        status:
          type: integer
        code:
          type: string
        detail:
          type: string
        request_id:
          type: string
        errors:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              message:
                type: string
            required:
            - field
            - message
        required_credits:
          type: number
        available_credits:
          type: number
        quota:
          type: string
        retry_after:
          type: integer
        next_step:
          type: string
      required:
      - type
      - title
      - status
      - code
      - detail
      - request_id
    CadFormat:
      type: string
      enum:
      - dxf
      - dwg
      description: Format actually delivered (a DWG may fall back to DXF if the DWG writer is unavailable).
    CadFileResult:
      oneOf:
      - type: object
        properties:
          status:
            type: string
            enum:
            - ready
          document_id:
            $ref: '#/components/schemas/DocumentId'
          format:
            $ref: '#/components/schemas/CadFormat'
          requested_format:
            $ref: '#/components/schemas/CadFormat'
          filename:
            type: string
          bytes:
            type: integer
          watermarked:
            type:
            - boolean
            - 'null'
            description: The free file carries an aginera.ai watermark; null when the server did not say.
          paid_with_credits:
            type: object
            properties:
              credits:
                type: integer
              credits_remaining:
                type:
                - number
                - 'null'
            required:
            - credits
            - credits_remaining
          download:
            type: object
            properties:
              url:
                type: string
                format: uri
              filename:
                type: string
              expires_at:
                type: string
                format: date-time
            required:
            - url
            - filename
            - expires_at
          note:
            type: string
        required:
        - status
        - document_id
        - format
        - requested_format
        - filename
        - bytes
        - watermarked
        - download
      - type: object
        properties:
          status:
            type: string
            enum:
            - purchase_required
          document_id:
            $ref: '#/components/schemas/DocumentId'
          format:
            $ref: '#/components/schemas/CadFormat'
          reason:
            type: string
            enum:
            - download_requires_purchase
            - dwg_requires_purchase
            - file_too_large
            - full_set_requires_purchase
          message:
            type: string
          sku:
            type: string
            enum:
            - cad_dwg
          price:
            type: object
            properties:
              usd_cents:
                type: integer
              price_usd:
                type: number
              local_currency_note:
                type: string
            required:
            - usd_cents
            - price_usd
            - local_currency_note
          credits:
            type: integer
            description: Credits the purchase costs when paid from the balance.
          credits_available:
            type:
            - boolean
            - 'null'
            description: Whether this account can pay it from credits right now (null = not checked).
          checkout_url:
            type: string
            format: uri
            description: Stripe checkout for the USER to open and complete. Never complete it on their behalf.
          checkout_expires_in_hours:
            type: number
          size_mb:
            type:
            - number
            - 'null'
          free_alternative:
            type:
            - string
            - 'null'
          next_step:
            type: string
        required:
        - status
        - document_id
        - format
        - reason
        - message
        - sku
        - price
        - credits
        - credits_available
        - free_alternative
        - next_step
  securitySchemes:
    oauth2:
      type: oauth2
      description: Client credentials (service mode, Microsoft Entra ID tenant of Aginera; request scope=api://<aginera-api-app-id>/.default; granular scopes are attached to the credential) or authorization code + PKCE (delegated mode via the Aginera authorization server; scopes are consented by the user).
      flows:
        clientCredentials:
          tokenUrl: https://login.microsoftonline.com/65f567a9-6e6a-4f81-863c-aea4ece1f8eb/oauth2/v2.0/token
          scopes:
            projects:read: View projects
            projects:write: Create and update projects
            projects:delete: Delete projects
            documents:read: View and download documents
            documents:write: Upload drawings
            documents:delete: Delete documents
            takeoffs:read: View takeoffs, items, routes and schedules
            takeoffs:run: Run takeoffs (uses credits)
            takeoffs:review: Accept, reject or adjust takeoff items
            takeoffs:delete: Delete takeoffs
            estimates:read: View estimates
            estimates:generate: Generate estimates (uses credits)
            exports:read: Download exports
            exports:create: Create exports
            billing:read: View credits and usage
            billing:write: Purchase credits
            events:read: Read the event log
            webhooks:manage: Manage webhook endpoints
            takeoffs:deep: Run deep (UI-parity) takeoffs
            interior:read: View floor-plan renders (dollhouse, room images, film)
            interior:generate: Render floor plans and start purchases on your account (uses credits; paid add-ons need your checkout)
            cad:convert: Convert PDF drawings to CAD (free to view; downloading the CAD file is a one-time purchase — paid from your credits only when you say so, otherwise via your own checkout)
            bim:read: View BIM coordination models
            bim:generate: Generate BIM models + embed URLs (uses credits)
            clash:run: Run clash detection + embed URLs (uses credits)
        authorizationCode:
          authorizationUrl: https://auth.aginera.ai/oauth/authorize
          tokenUrl: https://auth.aginera.ai/oauth/token
          refreshUrl: https://auth.aginera.ai/oauth/token
          scopes:
            projects:read: View projects
            projects:write: Create and update projects
            projects:delete: Delete projects
            documents:read: View and download documents
            documents:write: Upload drawings
            documents:delete: Delete documents
            takeoffs:read: View takeoffs, items, routes and schedules
            takeoffs:run: Run takeoffs (uses credits)
            takeoffs:review: Accept, reject or adjust takeoff items
            takeoffs:delete: Delete takeoffs
            estimates:read: View estimates
            estimates:generate: Generate estimates (uses credits)
            exports:read: Download exports
            exports:create: Create exports
            billing:read: View credits and usage
            billing:write: Purchase credits
            events:read: Read the event log
            webhooks:manage: Manage webhook endpoints
            takeoffs:deep: Run deep (UI-parity) takeoffs
            interior:read: View floor-plan renders (dollhouse, room images, film)
            interior:generate: Render floor plans and start purchases on your account (uses credits; paid add-ons need your checkout)
            cad:convert: Convert PDF drawings to CAD (free to view; downloading the CAD file is a one-time purchase — paid from your credits only when you say so, otherwise via your own checkout)
            bim:read: View BIM coordination models
            bim:generate: Generate BIM models + embed URLs (uses credits)
            clash:run: Run clash detection + embed URLs (uses credits)
x-refined-from:
- aginera-ai-openapi.json
- aginera-openapi.json
- aginera-openapi.yaml