GraphQL API Reference

Introduction

Preimage’s GraphQL API allows developers to programmatically access digital twin data, including projects, scans, inputs, outputs, annotations, virtual tours, and 3D model files.

It is used for:

Retrieving project, scan, and workspace data
Monitoring the processing status of scan outputs
Fetching measurements, virtual tours, and 3D output locations
Reading annotations and metadata

Authentication & Setup

The API is a single GraphQL endpoint. Authenticate every request with a workspace API key sent in the x-api-key header. Each API key is tied to a single workspace, and all queries are automatically scoped to that workspace.

POST https://api.preimage.ai/public/v1/graphql
x-api-key: <YOUR_API_KEY>
Content-Type: application/json

Visiting the endpoint in a browser opens the API explorer’s authentication flow at /public/v1/graphql/auth. Automatic schema discovery may be disabled; use the documented queries below if your client cannot load a schema.

Keep workspace API keys out of shared code, screenshots, and public client-side applications.

Make a request

Replace YOUR_WORKSPACE_API_KEY with the key for the workspace you want to query:

curl 'https://api.preimage.ai/public/v1/graphql' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_WORKSPACE_API_KEY' \
  --data '{"query":"query { workspace { id name } }"}'

Successful query results are returned under data. Also inspect the response’s errors field: a GraphQL request can return HTTP 200 while reporting a query error. Replace example IDs such as scan123 with IDs returned for your workspace.

Data Model Overview

Workspace
 └── Project
      └── Scan
           ├── Input (raw files: images, videos, point clouds) → Files, Annotations
           └── Output (processed data) → OutputParts, VirtualTour → HotSpots

The root Query exposes four entry points:

Field	Description
`workspace`	The workspace tied to your API key (contains its projects).
`project(id)`	A single project by ID.
`scan(id)`	A single scan by ID.
`file(id)`	A single file by ID.

There is no root projects, inputs, outputs, or files list query — those are always reached by nesting through workspace, project, or scan.

Usage Scenarios

1. Get All Projects in Your Workspace

Projects are accessed through the workspace root field (there is no top-level projects query).

query {
  workspace {
    name
    slug
    projects {
      id
      name
      createdAt
    }
  }
}

2. Fetch All Scans for a Project

query {
  project(id: "project123") {
    name
    scans {
      id
      description
      createdAt
      updatedAt
    }
  }
}

3. Retrieve Inputs Associated with a Scan

query {
  scan(id: "scan123") {
    inputs {
      id
      type
      sqKms
      metadata
      annotations {
        name
        description
      }
      files {
        name
        s3Path
      }
    }
  }
}

4. Check Output Status & Retrieve Data

query {
  scan(id: "scan123") {
    outputs {
      id
      type
      processingStartTime
      processingEndTime
      s3Path
      warnings
      errors
    }
  }
}

5. Fetch Hotspots in a Virtual Tour

Virtual tours belong to an output, so query them by walking from a scan to its outputs.

query {
  scan(id: "scan123") {
    outputs {
      id
      type
      virtualTour {
        isScaled
        hotspots {
          position
          rotation
          metadata
        }
      }
    }
  }
}

6. Update Your Workspace (Mutation)

The only mutation currently exposed by the public API updates the workspace description.

mutation {
  workspace {
    updateWorkspace(description: "Updated workspace description") {
      id
      name
      description
    }
  }
}

7. Look Up a Single Input on a Scan

Inputs can be filtered to a single record by ID via the input(id) field on a scan (there is no root inputs query).

query {
  scan(id: "scan123") {
    input(id: "input123") {
      id
      type
      sqKms
      metadata
    }
  }
}

8. Fetch a File by ID

Files are retrieved by ID, either from the root file query or nested under an input (there is no root files list query).

query {
  file(id: "file123") {
    name
    size
    s3Path
  }
}

Output Field Reference

Field	Description
`id`	Unique identifier
`type`	`OutputType` enum (see below)
`creditsUsed`	Credits consumed to generate this output
`processingStartTime`	When processing began
`processingEndTime`	When processing finished
`s3Path`	Location of the output
`warnings` / `errors`	Processing messages
`virtualTour`	Linked virtual tour, if applicable
`outputParts`	Individual parts that make up the output
`metadata`	Additional properties (type `Json`)

Enum values

OutputType: BINSEG, CAD, CUSTOM, DEM, DTM, FULLSEG, GAUSSIANSPLATS, HIGHACCURACYPOINTCLOUD, ORTHO, POINTCLOUD, SCHEMATICFLOORPLAN, SEGMENTATIONQUANTITIES, SPARSECLOUD, TEXTURE, VIRTUALTOUR
InputType: CUSTOM, IMAGES, POINTCLOUD, VIDEO
AnnotationType: CIRCLE, LINE, POINT, POLYGON

Best Practices

Use nested queries (workspace → project → scan → outputs) to reduce the number of requests.
Always fetch by id where possible to reduce response size.
Use the metadata field (type Json) to read additional properties stored on records.
Stay within the rate limit of 100 requests per 5 minutes.

Troubleshooting

Problem	Check
Authentication or access error	Use the correct workspace key and include the `x-api-key` header.
Unknown field or query error	Follow the documented nesting and field names; inspect the `errors` response.
Record unavailable	Check the ID and whether the record belongs to the workspace tied to your key.
Too many requests	Slow down requests to stay within the per-IP rate limit.

For help, email support@preimage.ai with the operation, error message, and approximate request time. Remove the API key from anything you send.