Upload, manage, and markup attachments — photos, videos, PDFs, spec sheets — using a two-step flow that returns short-lived signed AWS S3 POST tokens for direct browser-to-S3 upload. Markups support GeoJSON drawings, arrows, text, and measurement overlays, and can be flattened into image thumbnails.
openapi: 3.1.0
info:
title: Fieldwire Attachments and Media API
description: |
Two-step direct-to-S3 upload flow for project attachments — photos, video,
PDFs, drawings, spec pages — and the markup overlays drawn on top of them.
Clients first request a signed AWS S3 POST token (1-day TTL), then POST
the binary file directly to AWS, and finally register the attachment in
Fieldwire. Markups follow the GeoJSON Feature schema with `arrow`,
`drawing`, `measurement`, and `text` styles.
version: v3.1
contact:
name: Fieldwire Developer Support
url: https://developers.fieldwire.com/
license:
name: Fieldwire Terms of Service
url: https://www.fieldwire.com/terms/
servers:
- url: https://client-api.us.fieldwire.com/api/v3
description: US Region
- url: https://client-api.eu.fieldwire.com/api/v3
description: EU Region
security:
- BearerAuth: []
tags:
- name: S3 Tokens
description: Short-lived signed AWS POST tokens for direct-to-S3 uploads.
- name: Attachments
description: Project attachment lifecycle.
- name: Markups
description: GeoJSON-shaped markup overlays drawn on attachments and sheets.
paths:
/projects/{project_id}/aws_post_tokens:
post:
operationId: addAwsPostTokens
summary: Get AWS POST Token For Upload
description: |
Request a one-day signed AWS POST token that the client uses to upload
the binary directly to Amazon S3. The token contains the post URL,
policy, and form fields required for the S3 `POST object` operation;
clients then add a `file` form field and POST to AWS directly.
tags: [S3 Tokens]
parameters:
- $ref: '#/components/parameters/ProjectId'
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [filename, content_type]
properties:
filename:
type: string
content_type:
type: string
example: image/jpeg
size:
type: integer
format: int64
responses:
'200':
description: Signed POST token.
content:
application/json:
schema:
$ref: '#/components/schemas/AwsPostToken'
/projects/{project_id}/attachments:
get:
operationId: getAttachmentsInProject
summary: Get Attachments In Project
tags: [Attachments]
parameters:
- $ref: '#/components/parameters/ProjectId'
responses:
'200':
description: Attachment list.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Attachment'
post:
operationId: createAttachmentInProject
summary: Create Attachment In Project
description: |
Register an attachment after the binary has been uploaded to S3 via
the POST-token flow. The `aws_post_token_id` ties the registration
back to the previously issued token.
tags: [Attachments]
parameters:
- $ref: '#/components/parameters/ProjectId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AttachmentCreate'
responses:
'201':
description: Registered attachment.
content:
application/json:
schema:
$ref: '#/components/schemas/Attachment'
/projects/{project_id}/attachment_markups:
get:
operationId: getAttachmentMarkupsInProject
summary: Get Attachment Markups In Project
tags: [Markups]
parameters:
- $ref: '#/components/parameters/ProjectId'
responses:
'200':
description: Markup list.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/AttachmentMarkup'
post:
operationId: createAttachmentMarkupInProject
summary: Create Attachment Markup In Project
description: |
Create a markup overlay on an attachment. The `data` field follows the
GeoJSON Feature schema with `properties.style` in {`arrow`, `drawing`,
`measurement`, `text`} and `geometry.type` in {`LineString`, `Polygon`}.
tags: [Markups]
parameters:
- $ref: '#/components/parameters/ProjectId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AttachmentMarkupCreate'
responses:
'201':
description: Created markup.
content:
application/json:
schema:
$ref: '#/components/schemas/AttachmentMarkup'
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
parameters:
ProjectId:
name: project_id
in: path
required: true
schema:
type: integer
format: int64
schemas:
AwsPostToken:
type: object
properties:
id:
type: integer
format: int64
post_address:
type: string
format: uri
description: AWS S3 endpoint to POST to.
fields:
type: object
additionalProperties:
type: string
description: Form fields (key, policy, signature, etc.) required by S3.
expires_at:
type: string
format: date-time
Attachment:
type: object
properties:
id:
type: integer
format: int64
project_id:
type: integer
format: int64
filename:
type: string
content_type:
type: string
size:
type: integer
format: int64
url:
type: string
format: uri
thumb_url:
type: string
format: uri
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
AttachmentCreate:
type: object
required: [aws_post_token_id]
properties:
aws_post_token_id:
type: integer
format: int64
filename:
type: string
content_type:
type: string
AttachmentMarkup:
type: object
properties:
id:
type: integer
format: int64
attachment_id:
type: integer
format: int64
data:
$ref: '#/components/schemas/MarkupGeoJsonFeature'
author_user_id:
type: integer
format: int64
created_at:
type: string
format: date-time
AttachmentMarkupCreate:
type: object
required: [attachment_id, data]
properties:
attachment_id:
type: integer
format: int64
data:
$ref: '#/components/schemas/MarkupGeoJsonFeature'
MarkupGeoJsonFeature:
type: object
required: [type, properties, geometry]
properties:
type:
type: string
enum: [Feature]
properties:
type: object
properties:
style:
type: string
enum: [arrow, drawing, measurement, text]
color:
type: string
description: Hex colour, e.g. "#FF0000".
opacity:
type: number
format: double
width:
type: number
format: double
description:
type: string
fontSize:
type: integer
geometry:
type: object
properties:
type:
type: string
enum: [LineString, Polygon]
coordinates:
type: array
items:
type: array
items:
type: number
format: double