Fieldguide engagements API
Endpoints used to interact with Fieldguide Engagements
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/fieldguide-engagements-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Fieldguide Engagements API
description: An API for interacting with the [Fieldguide](https://fieldguide.io) platform
version: v1
contact: {}
servers:
- url: https://api.fieldguide.io
description: Fieldguide API
security:
- bearer: []
tags:
- name: engagements
description: Endpoints used to interact with Fieldguide Engagements
paths:
/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
- 'null'
default: 1
- name: per_page
required: false
in: query
schema:
type:
- number
- 'null'
default: 50
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:
- 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
- 'null'
default: 1
- name: per_page
required: false
in: query
schema:
type:
- number
- 'null'
default: 50
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'']`)
Forbidden (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.
Use 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:
- name: uuid
required: true
in: path
description: The UUID of the Job
schema:
format: uuid
type: string
responses:
'200':
description: The exported Engagement binder file metadata and download URL
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/EngagementExportRead'
'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 a generated Engagement binder report
tags:
- engagements
x-required-scopes:
- engagements:read
/v1/engagements/{uuid}/users:
get:
operationId: list_engagement_users_v1
parameters:
- name: uuid
required: true
in: path
description: The UUID of the Engagement to retrieve Users for
schema:
format: uuid
type: string
- name: page
required: false
in: query
schema:
type:
- number
- 'null'
default: 1
- name: per_page
required: false
in: query
schema:
type:
- number
- 'null'
default: 50
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 users on the Engagement Team for the specified Engagement
content:
application/json:
schema:
allOf:
- properties:
data:
type: array
items:
$ref: '#/components/schemas/EngagementUserRead'
- 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`, `users:read`)
'404':
description: Resource not found
'429':
description: Too many requests
summary: List the Engagement Team on an Engagement
tags:
- engagements
x-required-scopes:
- engagements:read
- users:read
patch:
operationId: add_engagement_users_v1
parameters:
- name: uuid
required: true
in: path
description: The UUID of the Engagement to add Users to
schema:
format: uuid
type: string
requestBody:
required: true
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/EngagementUserCreate'
responses:
'204':
description: No content. The Users were added to the Engagement Team successfully.
'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: Add Users to an Engagement Team
tags:
- engagements
x-required-scopes:
- engagements:write
delete:
operationId: remove_engagement_users_v1
parameters:
- name: uuid
required: true
in: path
description: The UUID of the Engagement to delete Users from
schema:
format: uuid
type: string
requestBody:
required: true
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/EngagementUserDelete'
responses:
'204':
description: No content. The Users were removed from the Engagement Team successfully.
'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: Remove Users from an Engagement Team
tags:
- engagements
x-required-scopes:
- engagements:write
/v1/engagements/{uuid}/requests:
get:
operationId: list_requests_by_engagement_v1
parameters:
- name: uuid
required: true
in: path
description: The UUID of the engagement to retrieve requests for
schema:
format: uuid
type: string
- name: statuses
required: false
in: query
description: Filter Requests by status. Repeat the query parameter for multiple statuses.
schema:
type: array
items:
$ref: '#/components/schemas/RequestStatus'
- name: client_owner_user_uuids
required: false
in: query
description: Filter Requests by the UUID of their Client Owner Users. Repeat the query parameter for multiple UUIDs.
schema:
type: array
items:
type: string
format: uuid
- name: due_date_before
required: false
in: query
description: Filter Requests to those with a due date before this date. Uses strict before semantics and excludes Requests with no due date.
schema:
format: date
example: '2024-05-01'
type: string
- name: page
required: false
in: query
schema:
type:
- number
- 'null'
default: 1
- name: per_page
required: false
in: query
schema:
type:
- number
- 'null'
default: 50
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 Requests for the Engagement
content:
application/json:
schema:
allOf:
- properties:
data:
type: array
items:
$ref: '#/components/schemas/RequestRead'
- 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 `requests:read`)
'404':
description: Resource not found
'429':
description: Too many requests
summary: List Requests that belong to the specified Engagement
tags:
- engagements
x-required-scopes:
- requests:read
/v1/engagements/{uuid}/sheets:
get:
operationId: list_sheets_by_engagement_v1
parameters:
- name: uuid
required: true
in: path
description: The UUID of the Engagement for which to get Sheets
schema:
format: uuid
type: string
- name: page
required: false
in: query
schema:
type:
- number
- 'null'
default: 1
- name: per_page
required: false
in: query
schema:
type:
- number
- 'null'
default: 50
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 Sheets to which the Engagement is linked
content:
application/json:
schema:
allOf:
- properties:
data:
type: array
items:
$ref: '#/components/schemas/SheetRead'
- 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`, `sheets:read`)
'404':
description: Resource not found
'429':
description: Too many requests
summary: List Sheets that belong to the specified Engagement
tags:
- engagements
x-required-scopes:
- engagements:read
- sheets:read
/v1/engagements/{uuid}/folders:
get:
operationId: list_engagement_folders_v1
parameters:
- name: uuid
required: true
in: path
description: The UUID of the Engagement for which to get Folders
schema:
format: uuid
type: string
- name: parent_folder_uuid
required: false
in: query
description: An optional UUID of the parent folder
schema:
format: uuid
type: string
- name: page
required: false
in: query
schema:
type:
- number
- 'null'
default: 1
- name: per_page
required: false
in: query
schema:
type:
- number
- 'null'
default: 50
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 list of Engagement Folders
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/EngagementFolderRead'
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden (requires scopes `engagements.files:read`)
'404':
description: Resource not found
'429':
description: Too many requests
summary: List Folders that belong to the specified Engagement
tags:
- engagements
x-required-scopes:
- engagements.files:read
/v1/engagements/{engagement_uuid}/folders/{folder_uuid}:
get:
operationId: get_engagement_folder_v1
parameters:
- name: engagement_uuid
required: true
in: path
description: The UUID of the Engagement from which to get a Folder
schema:
format: uuid
type: string
- name: folder_uuid
required: true
in: path
description: The UUID of the folder to fetch
schema:
format: uuid
type: string
responses:
'200':
description: The Engagement Folder with the specified UUID
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/EngagementFolderRead'
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden (requires scopes `engagements.files:read`)
# --- truncated at 32 KB (62 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/fieldguide/refs/heads/main/openapi/fieldguide-engagements-api-openapi.yml