Fieldguide
Fieldguide API

REST API for interacting with the Fieldguide platform — manage companies, engagements, requests, sheets (rows, columns, cells), files and folders, comments, milestones, controls, users, insights exports, jobs, and webhook subscriptions. Authenticated with bearer JWT / API tokens scoped by resource permission.
Documentation GitHub OpenAPI
OpenAPI Specification

{
  "openapi": "3.0.0",
  "paths": {
    "/v1/scopes": {
      "get": {
        "operationId": "list_scopes_v1",
        "parameters": [],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ScopeRead"
                  }
                }
              }
            }
          },
          "429": {
            "description": "Too many requests"
          }
        },
        "security": [
          {}
        ],
        "summary": "List available Scopes for the Fieldguide API",
        "tags": [
          "api"
        ]
      }
    },
    "/v1/token": {
      "get": {
        "operationId": "get_current_token_v1",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Metadata about the current authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "discriminator": {
                    "propertyName": "type",
                    "mapping": {
                      "api": "#/components/schemas/ApiTokenRead",
                      "jwt": "#/components/schemas/JwtTokenRead"
                    }
                  },
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/ApiTokenRead"
                    },
                    {
                      "$ref": "#/components/schemas/JwtTokenRead"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          }
        },
        "summary": "Get metadata about the current authentication token",
        "tags": [
          "api"
        ]
      }
    },
    "/v1/companies": {
      "get": {
        "operationId": "list_companies_v1",
        "parameters": [
          {
            "name": "type",
            "required": false,
            "in": "query",
            "description": "Filter to show companies of a specific type",
            "schema": {
              "$ref": "#/components/schemas/CompanyType"
            }
          },
          {
            "name": "uuids",
            "required": false,
            "in": "query",
            "description": "Filter Companies by UUID. Repeat the query parameter for multiple UUIDs.",
            "schema": {
              "type": "array",
              "items": {
                "type": "string",
                "format": "uuid"
              }
            }
          },
          {
            "name": "page",
            "required": false,
            "in": "query",
            "schema": {
              "type": "number",
              "default": 1,
              "nullable": true
            }
          },
          {
            "name": "per_page",
            "required": false,
            "in": "query",
            "schema": {
              "type": "number",
              "default": 50,
              "nullable": true,
              "minimum": 1,
              "maximum": 200
            }
          },
          {
            "name": "sort_order",
            "required": false,
            "in": "query",
            "description": "Sort order for paginated results. Use `desc` to reverse the default ascending order.",
            "schema": {
              "type": "string",
              "default": "asc",
              "enum": [
                "asc",
                "desc"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The Companies accessible by the user",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/CompanyRead"
                          }
                        }
                      }
                    },
                    {
                      "properties": {
                        "_links": {
                          "type": "object",
                          "required": [
                            "self",
                            "first",
                            "last"
                          ],
                          "properties": {
                            "self": {
                              "type": "object",
                              "description": "The URL for the current page being fetched",
                              "properties": {
                                "href": {
                                  "type": "string",
                                  "example": "https://api.fieldguide.io/v1/example?page=2&per_page=50"
                                }
                              }
                            },
                            "first": {
                              "type": "object",
                              "description": "The URL for the first page of the set",
                              "properties": {
                                "href": {
                                  "type": "string",
                                  "example": "https://api.fieldguide.io/v1/example?page=1&per_page=50"
                                }
                              }
                            },
                            "last": {
                              "type": "object",
                              "description": "The URL for the last page of the set",
                              "properties": {
                                "href": {
                                  "type": "string",
                                  "example": "https://api.fieldguide.io/v1/example?page=10&per_page=50"
                                }
                              }
                            },
                            "previous": {
                              "type": "object",
                              "description": "The URL for the previous page in the set, if there is one",
                              "properties": {
                                "href": {
                                  "type": "string",
                                  "example": "https://api.fieldguide.io/v1/example?page=1&per_page=50"
                                }
                              }
                            },
                            "next": {
                              "type": "object",
                              "description": "The URL for the next page in the set, if there is one",
                              "properties": {
                                "href": {
                                  "type": "string",
                                  "example": "https://api.fieldguide.io/v1/example?page=3&per_page=50"
                                }
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bad Request"
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden (requires scopes `companies:read`)"
          },
          "429": {
            "description": "Too many requests"
          }
        },
        "summary": "List available Companies",
        "tags": [
          "companies"
        ],
        "x-required-scopes": [
          "companies:read"
        ]
      },
      "post": {
        "operationId": "create_company_v1",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CompanyCreate"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The newly created Company",
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CompanyRead"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request"
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden (requires permission `['insert', 'companies']`)\n\nForbidden (requires scopes `companies:write`)"
          },
          "429": {
            "description": "Too many requests"
          }
        },
        "summary": "Create a new Company",
        "tags": [
          "companies"
        ],
        "x-required-scopes": [
          "companies:write"
        ]
      }
    },
    "/v1/companies/{uuid}": {
      "get": {
        "operationId": "get_company_v1",
        "parameters": [
          {
            "name": "uuid",
            "required": true,
            "in": "path",
            "description": "The UUID of the Company to retrieve",
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The Company data",
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CompanyRead"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request"
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden (requires scopes `companies:read`)"
          },
          "404": {
            "description": "Resource not found"
          },
          "429": {
            "description": "Too many requests"
          }
        },
        "summary": "Fetch the specified Company",
        "tags": [
          "companies"
        ],
        "x-required-scopes": [
          "companies:read"
        ]
      },
      "patch": {
        "operationId": "update_company_v1",
        "parameters": [
          {
            "name": "uuid",
            "required": true,
            "in": "path",
            "description": "The UUID of the Company to update",
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CompanyUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated Company",
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CompanyRead"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request"
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden (requires permission `['update', 'companies']`)\n\nForbidden (requires scopes `companies:write`)"
          },
          "404": {
            "description": "Resource not found"
          },
          "429": {
            "description": "Too many requests"
          }
        },
        "summary": "Update the specified Company",
        "tags": [
          "companies"
        ],
        "x-required-scopes": [
          "companies:write"
        ]
      }
    },
    "/v1/companies/{uuid}/engagements": {
      "get": {
        "operationId": "list_engagements_by_company_v1",
        "parameters": [
          {
            "name": "uuid",
            "required": true,
            "in": "path",
            "description": "The UUID of the Company to retrieve engagements from",
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          },
          {
            "name": "page",
            "required": false,
            "in": "query",
            "schema": {
              "type": "number",
              "default": 1,
              "nullable": true
            }
          },
          {
            "name": "per_page",
            "required": false,
            "in": "query",
            "schema": {
              "type": "number",
              "default": 50,
              "nullable": true,
              "minimum": 1,
              "maximum": 200
            }
          },
          {
            "name": "sort_order",
            "required": false,
            "in": "query",
            "description": "Sort order for paginated results. Use `desc` to reverse the default ascending order.",
            "schema": {
              "type": "string",
              "default": "asc",
              "enum": [
                "asc",
                "desc"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The Engagements for the specified Company",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/EngagementRead"
                          }
                        }
                      }
                    },
                    {
                      "properties": {
                        "_links": {
                          "type": "object",
                          "required": [
                            "self",
                            "first",
                            "last"
                          ],
                          "properties": {
                            "self": {
                              "type": "object",
                              "description": "The URL for the current page being fetched",
                              "properties": {
                                "href": {
                                  "type": "string",
                                  "example": "https://api.fieldguide.io/v1/example?page=2&per_page=50"
                                }
                              }
                            },
                            "first": {
                              "type": "object",
                              "description": "The URL for the first page of the set",
                              "properties": {
                                "href": {
                                  "type": "string",
                                  "example": "https://api.fieldguide.io/v1/example?page=1&per_page=50"
                                }
                              }
                            },
                            "last": {
                              "type": "object",
                              "description": "The URL for the last page of the set",
                              "properties": {
                                "href": {
                                  "type": "string",
                                  "example": "https://api.fieldguide.io/v1/example?page=10&per_page=50"
                                }
                              }
                            },
                            "previous": {
                              "type": "object",
                              "description": "The URL for the previous page in the set, if there is one",
                              "properties": {
                                "href": {
                                  "type": "string",
                                  "example": "https://api.fieldguide.io/v1/example?page=1&per_page=50"
                                }
                              }
                            },
                            "next": {
                              "type": "object",
                              "description": "The URL for the next page in the set, if there is one",
                              "properties": {
                                "href": {
                                  "type": "string",
                                  "example": "https://api.fieldguide.io/v1/example?page=3&per_page=50"
                                }
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bad Request"
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden (requires scopes `engagements:read`)"
          },
          "429": {
            "description": "Too many requests"
          }
        },
        "summary": "Get engagements for a given company",
        "tags": [
          "companies",
          "engagements"
        ],
        "x-required-scopes": [
          "engagements:read"
        ]
      }
    },
    "/v1/engagements": {
      "get": {
        "operationId": "list_engagements_v1",
        "parameters": [
          {
            "name": "templates",
            "required": false,
            "in": "query",
            "description": "Filter to include, exclude, or only show template engagements",
            "schema": {
              "$ref": "#/components/schemas/TemplatesQuery"
            }
          },
          {
            "name": "uuids",
            "required": false,
            "in": "query",
            "description": "Filter Engagements by UUID. Repeat the query parameter for multiple UUIDs.",
            "schema": {
              "type": "array",
              "items": {
                "type": "string",
                "format": "uuid"
              }
            }
          },
          {
            "name": "engagement_lead_user_uuid",
            "required": false,
            "in": "query",
            "description": "Filter Engagements by the UUID of their Engagement Lead User.",
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          },
          {
            "name": "client_owner_user_uuid",
            "required": false,
            "in": "query",
            "description": "Filter Engagements by the UUID of their Client Owner User.",
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          },
          {
            "name": "statuses",
            "required": false,
            "in": "query",
            "description": "Filter Engagements by status. Repeat the query parameter for multiple statuses.",
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/EngagementsQueryStatusLabel"
              }
            }
          },
          {
            "name": "page",
            "required": false,
            "in": "query",
            "schema": {
              "type": "number",
              "default": 1,
              "nullable": true
            }
          },
          {
            "name": "per_page",
            "required": false,
            "in": "query",
            "schema": {
              "type": "number",
              "default": 50,
              "nullable": true,
              "minimum": 1,
              "maximum": 200
            }
          },
          {
            "name": "sort_order",
            "required": false,
            "in": "query",
            "description": "Sort order for paginated results. Use `desc` to reverse the default ascending order.",
            "schema": {
              "type": "string",
              "default": "asc",
              "enum": [
                "asc",
                "desc"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The Engagements accessible by the user",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/EngagementRead"
                          }
                        }
                      }
                    },
                    {
                      "properties": {
                        "_links": {
                          "type": "object",
                          "required": [
                            "self",
                            "first",
                            "last"
                          ],
                          "properties": {
                            "self": {
                              "type": "object",
                              "description": "The URL for the current page being fetched",
                              "properties": {
                                "href": {
                                  "type": "string",
                                  "example": "https://api.fieldguide.io/v1/example?page=2&per_page=50"
                                }
                              }
                            },
                            "first": {
                              "type": "object",
                              "description": "The URL for the first page of the set",
                              "properties": {
                                "href": {
                                  "type": "string",
                                  "example": "https://api.fieldguide.io/v1/example?page=1&per_page=50"
                                }
                              }
                            },
                            "last": {
                              "type": "object",
                              "description": "The URL for the last page of the set",
                              "properties": {
                                "href": {
                                  "type": "string",
                                  "example": "https://api.fieldguide.io/v1/example?page=10&per_page=50"
                                }
                              }
                            },
                            "previous": {
                              "type": "object",
                              "description": "The URL for the previous page in the set, if there is one",
                              "properties": {
                                "href": {
                                  "type": "string",
                                  "example": "https://api.fieldguide.io/v1/example?page=1&per_page=50"
                                }
                              }
                            },
                            "next": {
                              "type": "object",
                              "description": "The URL for the next page in the set, if there is one",
                              "properties": {
                                "href": {
                                  "type": "string",
                                  "example": "https://api.fieldguide.io/v1/example?page=3&per_page=50"
                                }
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bad Request"
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden (requires scopes `engagements:read`)"
          },
          "429": {
            "description": "Too many requests"
          }
        },
        "summary": "List available Engagements",
        "tags": [
          "engagements"
        ],
        "x-required-scopes": [
          "engagements:read"
        ]
      }
    },
    "/v1/engagements/{uuid}": {
      "get": {
        "operationId": "get_engagement_v1",
        "parameters": [
          {
            "name": "uuid",
            "required": true,
            "in": "path",
            "description": "The UUID of the Engagement to retrieve",
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The Engagement details",
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/EngagementRead"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request"
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden (requires scopes `engagements:read`)"
          },
          "404": {
            "description": "Resource not found"
          },
          "429": {
            "description": "Too many requests"
          }
        },
        "summary": "Fetch the specified Engagement",
        "tags": [
          "engagements"
        ],
        "x-required-scopes": [
          "engagements:read"
        ]
      },
      "patch": {
        "operationId": "update_engagement_v1",
        "parameters": [
          {
            "name": "uuid",
            "required": true,
            "in": "path",
            "description": "The UUID of the Engagement to update",
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EngagementUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated Engagement data",
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/EngagementRead"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request"
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden (requires scopes `engagements:write`)"
          },
          "404": {
            "description": "Resource not found"
          },
          "429": {
            "description": "Too many requests"
          }
        },
        "summary": "Update the specified Engagement",
        "tags": [
          "engagements"
        ],
        "x-required-scopes": [
          "engagements:write"
        ]
      }
    },
    "/v1/engagements/from-template": {
      "post": {
        "description": "Creates a new Engagement based on an existing template Engagement. The request is accepted for asynchronous processing; the response returns the new Engagement's UUID, which may not be fully provisioned immediately.",
        "operationId": "create_engagement_from_template_v1",
        "parameters": [],
        "requestBody": {
          "required": true,
          "description": "Engagement creation from template options",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EngagementCreateFromTemplate"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "The Engagement creation has been accepted for processing",
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/EngagementUuidRead"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request"
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden (requires permission `['insert', 'engagements']`)\n\nForbidden (requires scopes `engagements:write`)"
          },
          "429": {
            "description": "Too many requests"
          }
        },
        "summary": "Create a new Engagement from a template",
        "tags": [
          "engagements"
        ],
        "x-required-scopes": [
          "engagements:write"
        ]
      }
    },
    "/v1/engagements/{uuid}/export": {
      "post": {
        "description": "Begins a long-running process that will generate an Engagement binder as a zip file.\n\nUse the Job ID that this endpoint returns with the appropriate [jobs endpoint](#/jobs/get_job_v1) to check its status and get its result.",
        "operationId": "export_engagement_v1",
        "parameters": [
          {
            "name": "uuid",
            "required": true,
            "in": "path",
            "description": "The UUID of the Engagement to export",
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "responses": {
          "202": {
            "headers": {
              "Location": {
                "description": "The URI to check the status of the job",
                "schema": {
                  "type": "string",
                  "example": "https://api.fieldguide.io/v1/jobs/f2c75e84-6b42-452d-b52f-3bf1854432d6"
                }
              },
              "Retry-After": {
                "description": "A date-time estimate of when the job will complete (if the job is still running)",
                "schema": {
                  "type": "string",
                  "format": "date-time",
                  "example": "2025-04-04T12:30:00.000Z"
                },
                "required": false
              }
            },
            "description": "The Job UUID for the Engagement binder export",
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/JobSubmittedRead"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request"
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden (requires scopes `engagements:read`)"
          },
          "404": {
            "description": "Resource not found"
          },
          "429": {
            "description": "Too many requests"
          }
        },
        "summary": "Export an Engagement binder",
        "tags": [
          "engagements"
        ],
        "x-required-scopes": [
          "engagements:read"
        ]
      }
    },
    "/v1/engagements/exports/{uuid}": {
      "get": {
        "description": "Returns the download URL and metadata for a completed Engagement binder export. Call this once the export Job returned by the export endpoint has finished.",
        "operationId": "get_engagement_export_v1",
        "parameters

# --- truncated at 32 KB (225 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/fieldguide/refs/heads/main/openapi/fieldguide-openapi-original.json
Fieldguide API

Documentation

Specifications

Other Resources

OpenAPI Specification
