# developer Agentforce Operations - Full Documentation Agentforce Operations API Reference # Agentforce Operations API Reference Use the Agentforce Operations REST API to access and manage workspace resources, including users, teams, blueprints, workflows, and roles. Authenticate by using OAuth 2.0 client credentials to get an access token. Every request requires two headers: `Authorization` and `X-Regrello-Workspace-ID`. To get started, see [Get Started with the Agentforce Operations REST API](/docs/platform/agentforce-operations/guide/agentforce-operations-rest-api-get-started.html). **Version:** 1.0 ## Servers * `/api/v1` REST API v1 Default security: oauth2. ## Security * `oauth2` (oauth2) OAuth 2.0 client credentials issued per workspace. Obtain a bearer token by POSTing `grant_type=client_credentials` with your service-account `client_id` and `client_secret` to `/oauth/{workspace-uuid}/token`. Every authenticated request must also include `X-Regrello-Workspace-ID: `. * OAuth flow clientCredentials (tokenUrl: /oauth/{workspace-uuid}/token) ## Tags ### Meta Health check and API specification endpoints. ### Users User management. ### Teams Team management. ### Views Saved views. ### Blueprints Blueprint management. ### Roles Role management ### Workflows Workflow management ## Operations ### GET Check API health `GET /health` Operation ID: `getHealth`. Tags: Meta. Verify that the API is reachable before making authenticated requests. No authentication required. #### Responses * **200** Service is healthy. Media type: `application/json`. Schema: `HealthResponse`. * **405** The HTTP method isn't allowed on this path. Media type: `application/json`. Schema: `ErrorResponse`. ### GET Get the OpenAPI specification `GET /openapi.json` Operation ID: `getOpenAPISpec`. Tags: Meta. Get the full OpenAPI 3.0 specification for the API, including all available endpoints, request and response schemas, authentication requirements, and pagination details. Use to generate client SDKs, import into Postman or Insomnia, or validate requests. No authentication required. #### Responses * **200** The full OpenAPI 3.0 specification. Media type: `application/json`. Schema: `object`. OpenAPI 3.0 document. ### GET List users `GET /users` Operation ID: `listUsers`. Tags: Users. Get a list of users in the workspace. This endpoint supports pagination. Pass `view=admin` to also enable ordering, searching, and filtering. #### Parameters * `view` (query, string) Specifies the query mode. Valid value: admin, which exposes the orderBy, searchQuery, and activeFilter parameters. Allowed values: `admin`. * `limit` (query, integer (int64)) The maximum number of items to return. Default value is `50`. Default: `50`. Minimum: 1. * `offset` (query, integer (int64)) The number of items to skip when returning pagination results. Valid values: zero or a positive integer. Minimum: 0. * `orderBy` (query, string) Specifies a `field:direction` value for ordering the user list. For example, to sort the user list ascending by name, enter `name:asc`. Available only when the `view` parameter is set to `admin`. * `searchQuery` (query, string) Specifies a string to filter the user list. Only users whose name or email address contains the string are returned. Available only when the `view` parameter is set to `admin`. * `activeFilter` (query, string) Specifies the activity status of the users to list. Valid values: `ACTIVE`, `DEACTIVATED`, `ALL`. Available only when the `view` parameter is set to `admin`. Allowed values: `ACTIVE`, `DEACTIVATED`, `ALL`. #### Responses * **200** A paginated list of users. Headers: * `SFDC-Pagination-Offset` (integer (int64)) The number of items skipped before these pagination results. Default value is `0`. * `SFDC-Pagination-Limit` (integer (int64)) The maximum number of items returned for these pagination results. Default value is `50`. * `SFDC-Pagination-Total-Count` (integer (int64)) The total number of items matching the query across all pages. Not all endpoints return this header. * `SFDC-Pagination-Result-Count` (integer (int64)) The number of items returned in this page of results. Media type: `application/json`. Schema: `array of User`. Array of `User`. * **400** The request is invalid or didn't pass validation. Media type: `application/json`. Schema: `ErrorResponse`. * **401** Missing or invalid authentication. Media type: `application/json`. Schema: `ErrorResponse`. * **403** You don't have permission to perform this action. Media type: `application/json`. Schema: `ErrorResponse`. * **405** The HTTP method isn't allowed on this path. Media type: `application/json`. Schema: `ErrorResponse`. * **500** An unexpected server error occurred. Media type: `application/json`. Schema: `ErrorResponse`. ### GET Get a user by ID `GET /users/{id}` Operation ID: `getUserById`. Tags: Users. Get a single user by ID. #### Parameters * `id` (path, integer (int64), required) The ID of the resource. #### Responses * **200** The requested user. Media type: `application/json`. Schema: `User`. * **400** The request is invalid or didn't pass validation. Media type: `application/json`. Schema: `ErrorResponse`. * **401** Missing or invalid authentication. Media type: `application/json`. Schema: `ErrorResponse`. * **403** You don't have permission to perform this action. Media type: `application/json`. Schema: `ErrorResponse`. * **404** The requested resource doesn't exist. Media type: `application/json`. Schema: `ErrorResponse`. * **405** The HTTP method isn't allowed on this path. Media type: `application/json`. Schema: `ErrorResponse`. * **500** An unexpected server error occurred. Media type: `application/json`. Schema: `ErrorResponse`. ### GET List teams `GET /teams` Operation ID: `getTeams`. Tags: Teams. Get a list of teams in the workspace, optionally filtered by search query. This endpoint supports pagination. #### Parameters * `searchQuery` (query, string) Specifies a string to filter the team list. Only teams with names that contain the string are returned. * `limit` (query, integer (int64)) The maximum number of items to return. Default value is `50`. Default: `50`. Minimum: 1. * `offset` (query, integer (int64)) The number of items to skip when returning pagination results. Valid values: zero or a positive integer. Minimum: 0. #### Responses * **200** A paginated list of teams. Headers: * `SFDC-Pagination-Offset` (integer (int64)) The number of items skipped before these pagination results. Default value is `0`. * `SFDC-Pagination-Limit` (integer (int64)) The maximum number of items returned for these pagination results. Default value is `50`. * `SFDC-Pagination-Total-Count` (integer (int64)) The total number of items matching the query across all pages. Not all endpoints return this header. * `SFDC-Pagination-Result-Count` (integer (int64)) The number of items returned in this page of results. Media type: `application/json`. Schema: `array of Team`. Array of `Team`. * **400** The request is invalid or didn't pass validation. Media type: `application/json`. Schema: `ErrorResponse`. * **401** Missing or invalid authentication. Media type: `application/json`. Schema: `ErrorResponse`. * **403** You don't have permission to perform this action. Media type: `application/json`. Schema: `ErrorResponse`. * **405** The HTTP method isn't allowed on this path. Media type: `application/json`. Schema: `ErrorResponse`. * **500** An unexpected server error occurred. Media type: `application/json`. Schema: `ErrorResponse`. ### GET Get a team by ID `GET /teams/{id}` Operation ID: `getTeamById`. Tags: Teams. Get a single team by ID. #### Parameters * `id` (path, integer (int64), required) The ID of the resource. #### Responses * **200** The requested team. Media type: `application/json`. Schema: `Team`. * **400** The request is invalid or didn't pass validation. Media type: `application/json`. Schema: `ErrorResponse`. * **401** Missing or invalid authentication. Media type: `application/json`. Schema: `ErrorResponse`. * **403** You don't have permission to perform this action. Media type: `application/json`. Schema: `ErrorResponse`. * **404** The requested resource doesn't exist. Media type: `application/json`. Schema: `ErrorResponse`. * **405** The HTTP method isn't allowed on this path. Media type: `application/json`. Schema: `ErrorResponse`. * **500** An unexpected server error occurred. Media type: `application/json`. Schema: `ErrorResponse`. ### PATCH Update a team `PATCH /teams/{id}` Operation ID: `updateTeam`. Tags: Teams. Update a team's name, administrators, and members. The `name` and `teamAdminIds` fields are required, and the `memberIds` field is optional. The `teamAdminIds` array must contain at least one ID. #### Parameters * `id` (path, integer (int64), required) The ID of the resource. #### Request body (required) Media type: `application/json`. Schema: `UpdateTeamInput`. #### Responses * **200** The updated team. Media type: `application/json`. Schema: `Team`. * **400** The request is invalid or didn't pass validation. Media type: `application/json`. Schema: `ErrorResponse`. * **401** Missing or invalid authentication. Media type: `application/json`. Schema: `ErrorResponse`. * **403** You don't have permission to perform this action. Media type: `application/json`. Schema: `ErrorResponse`. * **404** The requested resource doesn't exist. Media type: `application/json`. Schema: `ErrorResponse`. * **405** The HTTP method isn't allowed on this path. Media type: `application/json`. Schema: `ErrorResponse`. * **409** The request can't be completed because the specified name is already in use. Media type: `application/json`. Schema: `ErrorResponse`. * **415** Set the Content-Type header to `application/json` for POST, PUT, and PATCH requests. Media type: `application/json`. Schema: `ErrorResponse`. * **500** An unexpected server error occurred. Media type: `application/json`. Schema: `ErrorResponse`. ### GET Get a view's workflows `GET /views/{viewId}` Operation ID: `getViewById`. Tags: Views. Get a list of workflows in a saved view, excluding the view's name, filters, and sort order metadata. This endpoint supports pagination. #### Parameters * `viewId` (path, integer (int64), required) Specifies the ID of the view to retrieve workflows for. * `limit` (query, integer (int64)) The maximum number of items to return. Default value is `50`. Default: `50`. Minimum: 1. * `offset` (query, integer (int64)) The number of items to skip when returning pagination results. Valid values: zero or a positive integer. Minimum: 0. #### Responses * **200** A paginated list of workflows in the view. Headers: * `SFDC-Pagination-Offset` (integer (int64)) The number of items skipped before these pagination results. Default value is `0`. * `SFDC-Pagination-Limit` (integer (int64)) The maximum number of items returned for these pagination results. Default value is `50`. * `SFDC-Pagination-Total-Count` (integer (int64)) The total number of items matching the query across all pages. Not all endpoints return this header. * `SFDC-Pagination-Result-Count` (integer (int64)) The number of items returned in this page of results. Media type: `application/json`. Schema: `array of WorkflowSummary`. Array of `WorkflowSummary`. * **400** The request is invalid or didn't pass validation. Media type: `application/json`. Schema: `ErrorResponse`. * **401** Missing or invalid authentication. Media type: `application/json`. Schema: `ErrorResponse`. * **403** You don't have permission to perform this action. Media type: `application/json`. Schema: `ErrorResponse`. * **404** The requested resource doesn't exist. Media type: `application/json`. Schema: `ErrorResponse`. * **405** The HTTP method isn't allowed on this path. Media type: `application/json`. Schema: `ErrorResponse`. * **500** An unexpected server error occurred. Media type: `application/json`. Schema: `ErrorResponse`. ### GET List blueprints `GET /blueprints` Operation ID: `listBlueprints`. Tags: Blueprints. Get a list of workspace blueprints that have been published at least once. This endpoint supports optional search, filtering, and pagination. #### Parameters * `limit` (query, integer (int64)) The maximum number of items to return. Default value is `50`. Default: `50`. Minimum: 1. * `offset` (query, integer (int64)) The number of items to skip when returning pagination results. Valid values: zero or a positive integer. Minimum: 0. * `search` (query, string) Specifies a string to filter the blueprints list. Only blueprints with names or descriptions that contain the string are returned. * `includeDeleted` (query, boolean) Specifies whether to include soft-deleted blueprints in the list. Default value is `false`. #### Responses * **200** A paginated list of blueprints. Headers: * `SFDC-Pagination-Offset` (integer (int64)) The number of items skipped before these pagination results. Default value is `0`. * `SFDC-Pagination-Limit` (integer (int64)) The maximum number of items returned for these pagination results. Default value is `50`. * `SFDC-Pagination-Total-Count` (integer (int64)) The total number of items matching the query across all pages. Not all endpoints return this header. * `SFDC-Pagination-Result-Count` (integer (int64)) The number of items returned in this page of results. Media type: `application/json`. Schema: `array of Blueprint`. Array of `Blueprint`. * **400** The request is invalid or didn't pass validation. Media type: `application/json`. Schema: `ErrorResponse`. * **401** Missing or invalid authentication. Media type: `application/json`. Schema: `ErrorResponse`. * **403** You don't have permission to perform this action. Media type: `application/json`. Schema: `ErrorResponse`. * **405** The HTTP method isn't allowed on this path. Media type: `application/json`. Schema: `ErrorResponse`. * **500** An unexpected server error occurred. Media type: `application/json`. Schema: `ErrorResponse`. ### GET Get a blueprint by UUID `GET /blueprints/{uuid}` Operation ID: `getBlueprintByUuid`. Tags: Blueprints. Get a single blueprint by its UUID, including its intake form field metadata. #### Parameters * `uuid` (path, string, required) The short-form blueprint identifier. For example `EOz-Q0rVTRo`. This identifier is stable across blueprint versions. Pattern: ^\[A-Za-z0-9\_-\]{11}$. #### Responses * **200** The requested blueprint. Media type: `application/json`. Schema: `BlueprintDetail`. * **400** The request is invalid or didn't pass validation. Media type: `application/json`. Schema: `ErrorResponse`. * **401** Missing or invalid authentication. Media type: `application/json`. Schema: `ErrorResponse`. * **403** You don't have permission to perform this action. Media type: `application/json`. Schema: `ErrorResponse`. * **404** The requested resource doesn't exist. Media type: `application/json`. Schema: `ErrorResponse`. * **405** The HTTP method isn't allowed on this path. Media type: `application/json`. Schema: `ErrorResponse`. * **500** An unexpected server error occurred. Media type: `application/json`. Schema: `ErrorResponse`. ### GET Get the OpenAPI schema for a blueprint `GET /blueprints/{uuid}/schema` Operation ID: `getBlueprintSchema`. Tags: Blueprints. Get a self-contained OpenAPI 3.0.3 JSON document that describes how to create a workflow from the specified blueprint. The document's IntakeFormFields schema is dynamically generated from the blueprint's intake form fields. You can import the response directly into Postman, Swagger UI, or any OAS-compatible tooling. #### Parameters * `uuid` (path, string, required) The short-form blueprint identifier. For example `EOz-Q0rVTRo`. This identifier is stable across blueprint versions. Pattern: ^\[A-Za-z0-9\_-\]{11}$. #### Responses * **200** A self-contained OpenAPI 3.0.3 document. The top-level structure includes `openapi`, `info`, `paths`, `components`, `servers`, `security`, and `x-regrello-blueprint` (blueprint metadata). Media type: `application/json`. Schema: `object`. An OpenAPI 3.0.3 document (free-form structure). * **400** The request is invalid or didn't pass validation. Media type: `application/json`. Schema: `ErrorResponse`. * **401** Missing or invalid authentication. Media type: `application/json`. Schema: `ErrorResponse`. * **403** You don't have permission to perform this action. Media type: `application/json`. Schema: `ErrorResponse`. * **404** The requested resource doesn't exist. Media type: `application/json`. Schema: `ErrorResponse`. * **405** The HTTP method isn't allowed on this path. Media type: `application/json`. Schema: `ErrorResponse`. * **500** An unexpected server error occurred. Media type: `application/json`. Schema: `ErrorResponse`. ### GET List roles `GET /roles` Operation ID: `getRoles`. Tags: Roles. Get a list of roles in the workspace. This endpoint supports optional free-text search and pagination. #### Parameters * `search` (query, string) Specifies a string to filter the roles list. Only roles with names that contain the string are returned. * `limit` (query, integer (int64)) The maximum number of items to return. Default value is `50`. Default: `50`. Minimum: 1. * `offset` (query, integer (int64)) The number of items to skip when returning pagination results. Valid values: zero or a positive integer. Minimum: 0. * `includeCounts` (query, boolean, empty value allowed) Specifies whether to include `memberCount` and `usedInWorkflowTemplates` counts for each role. To include counts, pass the parameter without a value, for example `?includeCounts`. #### Responses * **200** A paginated list of roles. Headers: * `SFDC-Pagination-Offset` (integer (int64)) The number of items skipped before these pagination results. Default value is `0`. * `SFDC-Pagination-Limit` (integer (int64)) The maximum number of items returned for these pagination results. Default value is `50`. * `SFDC-Pagination-Total-Count` (integer (int64)) The total number of items matching the query across all pages. Not all endpoints return this header. * `SFDC-Pagination-Result-Count` (integer (int64)) The number of items returned in this page of results. Media type: `application/json`. Schema: `array of RoleEntry`. Array of `RoleEntry`. * **400** The request is invalid or didn't pass validation. Media type: `application/json`. Schema: `ErrorResponse`. * **401** Missing or invalid authentication. Media type: `application/json`. Schema: `ErrorResponse`. * **403** You don't have permission to perform this action. Media type: `application/json`. Schema: `ErrorResponse`. * **405** The HTTP method isn't allowed on this path. Media type: `application/json`. Schema: `ErrorResponse`. * **500** An unexpected server error occurred. Media type: `application/json`. Schema: `ErrorResponse`. ### GET Get a workflow by ID `GET /workflows/{id}` Operation ID: `getWorkflowById`. Tags: Workflows. Get a single workflow by ID, including its current status, name, reference number, and key timestamps. #### Parameters * `id` (path, integer (int64), required) The ID of the resource. #### Responses * **200** The requested workflow. Media type: `application/json`. Schema: `Workflow`. * **400** The request is invalid or didn't pass validation. Media type: `application/json`. Schema: `ErrorResponse`. * **401** Missing or invalid authentication. Media type: `application/json`. Schema: `ErrorResponse`. * **403** You don't have permission to perform this action. Media type: `application/json`. Schema: `ErrorResponse`. * **404** The requested resource doesn't exist. Media type: `application/json`. Schema: `ErrorResponse`. * **405** The HTTP method isn't allowed on this path. Media type: `application/json`. Schema: `ErrorResponse`. * **500** An unexpected server error occurred. Media type: `application/json`. Schema: `ErrorResponse`. ### POST Create a workflow from a blueprint `POST /workflows` Operation ID: `createWorkflow`. Tags: Workflows. Create a single workflow from the specified blueprint. The response includes the created workflow and a `Location` header pointing to the new resource. If `startImmediately` is `true` but the workflow fails to start due to missing required fields, the API still creates the workflow and returns a warning. #### Request body (required) Media type: `application/json`. Schema: `CreateWorkflowInput`. #### Responses * **201** Workflow created successfully. Headers: * `Location` (string) URL of the newly created workflow. Example: `/api/v1/workflows/789`. Media type: `application/json`. Schema: `CreateWorkflowResponse`. * **400** The request is invalid or didn't pass validation. Media type: `application/json`. Schema: `ErrorResponse`. * **401** Missing or invalid authentication. Media type: `application/json`. Schema: `ErrorResponse`. * **403** You don't have permission to perform this action. Media type: `application/json`. Schema: `ErrorResponse`. * **404** The requested resource doesn't exist. Media type: `application/json`. Schema: `ErrorResponse`. * **409** The request can't be completed because the specified name is already in use. Media type: `application/json`. Schema: `ErrorResponse`. * **415** Set the Content-Type header to `application/json` for POST, PUT, and PATCH requests. Media type: `application/json`. Schema: `ErrorResponse`. * **500** An unexpected server error occurred. Media type: `application/json`. Schema: `ErrorResponse`. ## Schemas ### HealthResponse * `status` (_string_, required) Example: `ok`. ### ErrorResponse * `errors` (_array of ErrorDetail_, required) ### User * `id` (_string_, required) User ID. * `name` (_string_, required) * `email` (_string (email)_, required) * `accessLevel` (_string_, required) The type of account the user holds, which determines their baseline level of access to the workspace. Valid values: INTERNAL, EXTERNAL, LIMITED. Internal users have full workspace access, including visibility into all users and teams. External users have limited access and can see only users they've previously shared a task with. Limited users don't have direct access to the workspace. They can access tasks only through web forms and email. * `createdDate` (_string (date-time)_, required) * `deletedDate` (_string (date-time)_, nullable) ### Team * `id` (_string_, required) * `name` (_string_, required) * `type` (_string_, required) Specifies the default level of workspace access for team members. Valid values: `Internal`, `External`. * `domain` (_string_) The email domain or domains associated with the team, derived from its members' email addresses. For external teams, this is the domain of the first member. For internal teams, this is a comma-separated list of all distinct member domains, sorted alphabetically. * `createdDate` (_string (date-time)_, required) * `deletedDate` (_string (date-time)_, nullable) * `teamMembers` (_array of TeamMember_) The administrators and members of the team. ### UpdateTeamInput * `name` (_string_, required) The new team display name. * `teamAdminIds` (_array of integer (int64)_, required) The IDs of users to designate as team administrators. Specify at least one ID. Minimum items: 1. * `memberIds` (_array of integer (int64)_) The IDs of the users who are team members. ### WorkflowSummary A view of a workflow returned when listing workflows in a saved view. Includes fields such as status, progress, dates, exception flag, creator, owner, and tags. * `id` (_string_, required) * `name` (_string_, required) * `createdDate` (_string (date-time)_, required) * `lastModifiedDate` (_string (date-time)_, required) * `scheduleStatus` (_string_, required) The current lifecycle status of the workflow. Valid values: NOT\_STARTED, STARTED, PAUSED, COMPLETED, ENDED. NOT\_STARTED — the workflow hasn't started yet, including workflows created with startImmediately set to false and workflows scheduled to start at a future date. STARTED — the workflow is running. PAUSED — a user manually paused the workflow. COMPLETED — the workflow ran to completion; all tasks that met their conditions finished. ENDED — a user manually ended the workflow before all tasks that met their conditions finished. Allowed values: `NOT_STARTED`, `STARTED`, `PAUSED`, `COMPLETED`, `ENDED`. * `startedDate` (_string (date-time)_, nullable) The date and time that the workflow started. This can be later than createdDate if the workflow was created but not started immediately. If the workflow hasn't started, this value is null. * `endDate` (_string (date-time)_, nullable) The projected date and time that the workflow is expected to finish, calculated from its stage and task dependencies and predicted durations. If the end date can't be calculated, this value is null. * `percentComplete` (_number (double)_, required) The workflow's completion progress as a percentage. The percentage is calculated as completed tasks divided by the total number of tasks in stages that met their conditions. Rejected tasks aren't counted as complete. A workflow with rejected tasks can't reach 100% until those tasks are either approved or skipped. * `exception` (_boolean_, required) Specifies whether a workflow has a reported problem. If true, at least one task has a flagged exception. Exceptions can result from a failed automated task, a manual problem report, or a task rejection. When this value is true, inspect the workflow's tasks to find the task flagged with the exception. * `createdBy` (_NestedParty_) The user who created the workflow. * `owner` (_NestedOwner_) The user or team who currently owns the workflow. The owner receives special access and status-update emails, and can be reassigned after workflow creation. If the owner is a team instead of an individual user, the user property is null. * `tags` (_array of NestedTag_) ### Blueprint A reusable template that defines a process, including its stages, tasks, and the fields that collect information. * `id` (_string_, required) * `name` (_string_, required) * `description` (_string_, nullable) * `type` (_string_, required) The blueprint's type. The API returns only the current version of published blueprints, so this value is always COMPANY. * `blueprintUuid` (_string (uuid)_, required) The short-form blueprint identifier. * `numberOfStages` (_integer (int64)_, required) The number of stages in the blueprint. * `versionNumber` (_integer (int64)_, required) The blueprint version number. ### BlueprintDetail A blueprint with full field and intake form details. Includes all fields of `Blueprint`. * `description` (_string_, nullable) * `type` (_string_) Allowed values: `MINE`, `COMPANY`, `VARIANT`. * `numberOfStages` (_integer_) * `versionNumber` (_integer_) * `fields` (_array of BlueprintField_) The fields from the blueprint's intake form that can be set via the REST API when creating a workflow. If the blueprint has no intake form, the returned array is empty. * `fieldsNotSupportedByRestApi` (_array of BlueprintFieldUnsupported_) The fields that exist on the blueprint's intake form but can't be set via the REST API, such as documents, signatures, and synced objects. Values for these fields must be set in the UI. If no values exist, the returned array is empty. ### RoleEntry A role with optional usage and membership counts. * `role` (_Role_, required) * `usedInWorkflowTemplates` (_integer (int64)_, nullable) The number of workflow templates that use this role. If the `includeCounts` parameter isn't specified, this value is null. * `memberCount` (_integer (int64)_, nullable) The number of members assigned this role. If the `includeCounts` parameter isn't specified, this value is null. ### Workflow A single running instance of a blueprint, with its own data, assignees, and timeline. * `id` (_string_, required) * `name` (_string_, required) * `scheduleStatus` (_string_, required) The current lifecycle status of the workflow. Valid values: NOT\_STARTED, STARTED, PAUSED, COMPLETED, ENDED. NOT\_STARTED — the workflow hasn't started yet, including workflows created with startImmediately set to false and workflows scheduled to start at a future date. STARTED — the workflow is running. PAUSED — a user manually paused the workflow. COMPLETED — the workflow ran to completion; all tasks that met their conditions finished. ENDED — a user manually ended the workflow before all tasks that met their conditions finished. Allowed values: `NOT_STARTED`, `STARTED`, `PAUSED`, `COMPLETED`, `ENDED`. * `referenceNumberPrefix` (_string_, nullable) The text portion of the workflow's reference number. The workflow's reference number is formatted as PREFIX-NUMBER. For example, in ECO-23, ECO is the referenceNumberPrefix and 23 is the referenceNumber. If the blueprint wasn't configured with a custom workflow reference number, this value is null. * `referenceNumber` (_integer (int64)_, nullable) The numeric portion of the workflow's reference number. The workflow's reference number is formatted as PREFIX-NUMBER. For example, in ECO-23, ECO is the referenceNumberPrefix and 23 is the referenceNumber. If the blueprint wasn't configured with a custom workflow reference number, this value is null. * `createdDate` (_string (date-time)_, required) * `lastModifiedDate` (_string (date-time)_, required) * `endedDate` (_string (date-time)_, nullable) The date and time that a user manually ended the workflow. If the workflow hasn't been manually ended, this value is null. ### CreateWorkflowInput * `blueprintUuid` (_string_, required) The short-form blueprint identifier. For example, `XAv-GzphRKU`. This identifier is stable across blueprint versions. Pattern: ^\[A-Za-z0-9\_-\]{11}$. * `name` (_string_) The workflow name. If the blueprint is configured to autogenerate workflow names, this value is appended to the autogenerated name as a suffix. If omitted, the blueprint's default name is used. * `startImmediately` (_boolean_) Specifies whether to start the workflow immediately after creation. Default value is `false`. If the workflow fails to start, it's still created and the response includes a warning. Default: `false`. * `inputs` (_object_) The field values for the blueprint's intake form, keyed by `field_`. The `id` is the field identifier returned in the `fields` array from the blueprint detail. Value format depends on the field type: * **TEXT, EMAIL, PHONE**: `string` * **NUMBER**: `integer` * **CURRENCY**: `number` (decimal) * **CHECKBOX**: `boolean` * **DATE**: `string` (ISO 8601 date, for example `"2026-05-15"`) * **SELECT**: `string` (must match an allowed value) * **MULTISELECT**: `string[]` (each must match an allowed value) * **PEOPLE (single)**: `{"type": "user", "email": "..."}` or `{"type": "team", "name": "..."}` * **PEOPLE (multi)**: array of the above objects * **ROLE**: `string` (email address of the user to assign to this role-restricted field) Unsupported field types (DOCUMENT, SIGNATURE, SYNCED\_OBJECT) can't be set via this endpoint. If included, the request is rejected with a 400 error. _Example_ ``` { "field_1234": "Acme Corp", "field_721": 42, "field_888": "High", "field_889": [ "Option A", "Option B" ], "field_999": { "type": "user", "email": "jane@example.com" }, "field_500": true, "field_501": "2026-05-15", "field_502": 99.99, "field_600": "approver@example.com" } ``` ### CreateWorkflowResponse * `id` (_string_, required) The unique identifier of the created workflow. * `x-regrello-blueprint` (_object_) Metadata about the blueprint that this workflow was created from. If the blueprint can't be resolved, this value is null. * `id` (_integer (int64)_, required) The blueprint ID. * `name` (_string_, required) The blueprint name. * `uuid` (_string_, required) The short-form blueprint identifier. * `description` (_string_) The blueprint description. If the blueprint has no description, this value is null. * `createdAt` (_string (date-time)_) The date and time that the blueprint was created. If unavailable, this value is null. * `updatedAt` (_string (date-time)_) The date and time that the blueprint was last updated. If unavailable, this value is null. * `publishedAt` (_string (date-time)_) The date and time that the blueprint was last published. If unavailable, this value is null. * `predictedDurationDays` (_integer_) The predicted duration of the workflow in days. If unavailable, this value is null. * `numberOfStages` (_integer_, required) The number of stages in the blueprint. * `versionNumber` (_integer_, required) The blueprint version number. * `name` (_string_, required) The workflow name. * `status` (_string_, required) The workflow's schedule status. Allowed values: `NOT_STARTED`, `STARTED`, `PAUSED`, `COMPLETED`, `ENDED`. * `createdDate` (_string (date-time)_, required) The date and time that the workflow was created. * `warnings` (_array of string_) Non-blocking warnings about the workflow creation. If no warnings exist, the returned array is empty. Warnings can include unresolvable PEOPLE references or start failures when `startImmediately` is `true`. ### ErrorDetail * `errorCode` (_string_, required) A broad HTTP-level error category, such as BAD\_REQUEST, NOT\_FOUND, or INTERNAL\_ERROR. * `messageCode` (_string_, required) A specific machine-readable reason, such as INVALID\_PARAMETER or OBJECT\_NOT\_FOUND. * `message` (_string_, required) A description of the error that's suitable for displaying or logging. * `targets` (_array of ErrorTarget_, required) The inputs that caused the error, such as a query parameter or body field. * `parameters` (_array of ErrorParameter_, required) The name-value pairs referenced by the error message. ### TeamMember A person who belongs to a team and whether they're a team administrator or simply a member. * `user` (_NestedUser_, required) * `admin` (_boolean_, required) Specifies whether the member is an administrator for the team. ### NestedParty A reference to the user or team associated with a workflow property. If the reference is to a team rather than an individual user, the user property is null. * `party` (_object_, required) * `id` (_string_, required) * `user` (_NestedUser_) ### NestedOwner A reference to the user or team that owns a workflow. If the owner is a team rather than an individual user, the user property is null. * `id` (_string_, required) * `user` (_NestedUser_) ### NestedTag * `id` (_string_, required) * `name` (_string_, required) ### BlueprintField A field on the blueprint's intake form that can be set via the REST API. * `id` (_integer (int64)_) The unique identifier for this version of the field definition. Fields are versioned, so this ID is specific to the version attached to this blueprint. * `name` (_string_) The field's display name. * `fieldType` (_string_) The field's data type. Allowed values: `CHECKBOX`, `CURRENCY`, `DATE`, `EMAIL`, `MULTISELECT`, `NUMBER`, `PEOPLE`, `PHONE`, `ROLE`, `SELECT`, `TEXT`. * `fieldUnit` (_string_, nullable) The currency name for CURRENCY fields, such as USD, EUR, or GBP. If the field type isn't CURRENCY, this value is null. * `required` (_boolean_) Specifies whether this field is required when creating a workflow. * `multiValued` (_boolean_, nullable) Specifies whether this field accepts multiple values. If the field type isn't SELECT, MULTISELECT, PEOPLE, or ROLE, this value is null. * `description` (_string_) A field description that's suitable for displaying or logging. * `allowedValues` (_array of string_) The allowed values for SELECT and MULTISELECT fields. If the field type isn't SELECT or MULTISELECT, this value is null. * `constraints` (_array of BlueprintFieldConstraint_, nullable) The validation constraints for this field. If no constraints exist, this value is null. * `exampleValue` (_any_) A representative example value for this field type. Depending on the field type, the value can be a string, array, or object. ### BlueprintFieldUnsupported A field on the blueprint's intake form that can't be set via the REST API. Values for this field must be set in the UI. * `id` (_integer (int64)_) The unique identifier for this version of the field definition. Fields are versioned, so this ID is specific to the version attached to this blueprint. * `name` (_string_) The field's display name. * `fieldType` (_string_) The field's data type. Allowed values: `DOCUMENT`, `SIGNATURE`, `SYNCED_OBJECT`. * `required` (_boolean_) Specifies whether this field is required when creating a workflow. * `multiValued` (_boolean_, nullable) Specifies whether this field accepts multiple values. If the field type isn't SELECT, MULTISELECT, or PEOPLE, this value is null. * `description` (_string_) ### Role A system-defined or custom role that determines what a user can do in Agentforce Operations. Only custom roles can be created, modified, and deleted. * `id` (_string_, required) * `name` (_string_, required) * `systemDefined` (_boolean_, required) Specifies whether this is a system-defined role. * `createdDate` (_string (date-time)_, required) * `lastModifiedDate` (_string (date-time)_) * `deletedDate` (_string (date-time)_, nullable) * `workspaceInviteAllowed` (_boolean_) Specifies whether users assigned this role can invite other users to the workspace. * `scimId` (_string_, nullable) The SCIM (System for Cross-domain Identity Management) identifier that links this role to an external identity provider. If the role isn't linked to an external identity provider, this value is null. ### ErrorTarget * `type` (_string_, required) The type of input that caused the error, such as QUERY\_PARAMETER, PATH\_PARAMETER, or FIELD. * `reference` (_string_, required) The name of the input that caused the error. ### ErrorParameter * `name` (_string_, required) The parameter name. * `value` (_string_, required) The parameter value. ### NestedUser A user referenced by another resource, including their ID, name, and email address. * `id` (_string_, required) * `name` (_string_, required) * `email` (_string (email)_, required) ### BlueprintFieldConstraint A validation constraint on a blueprint field. * `rule` (_string_) The constraint rule name. Allowed values: `ACCEPTED_DATES`, `DECIMAL_PLACES`, `MARKDOWN_FORMATTED`, `MAX_CHARACTERS`, `MAX_VALUE`, `MIN_CHARACTERS`, `MIN_VALUE`, `REGEX`. * `args` (_array of string_) The arguments for the constraint rule. ### PeopleValue A reference to a user or team for PEOPLE-type fields. * `type` (_string_, required) Specifies whether this field references a user or a team. Allowed values: `user`, `team`. * `email` (_string (email)_) The user's email address. If `type` is `user`, this field is required. * `name` (_string_) The team's name. If `type` is `team`, this field is required. If the name isn't unique within the workspace, the request fails with a 400 error. # Get Started with the Agentforce Operations REST API Use the Agentforce Operations REST API to access and manage workspace resources, such as blueprints, workflows, and users. This guide shows you how to set up authentication and make an API call. ## Prerequisites Before you begin: - You have an active Agentforce Operations workspace. - You have an Admin role in your Agentforce Operations workspace. ## Overview All REST API calls to your Agentforce Operations workspace require two values: an OAuth access token and a workspace UUID. Get the OAuth access token by using a service account's client ID and client secret. Access tokens expire after 2 hours. Find your workspace UUID in your browser's developer tools. This guide walks you through: 1. Creating a service account and saving its credentials 2. Finding your workspace UUID 3. Requesting an OAuth access token 4. Making your first API call ## Create a Service Account A service account is a dedicated API-only user in your Agentforce Operations workspace. Unlike a regular user account, a service account authenticates programmatically by using a client ID and client secret rather than a username and password. To create the account, use your admin session credentials. After you create it, you use the service account's client ID and client secret to request OAuth access tokens for all REST API calls. 1. Log in to your Agentforce Operations Admin page. ![Agentforce Operations Admin Page](https://developer.salesforce.com/docs/media/1admin.png) 2. Select the **Add or update** button in the People tab. ![Agentforce Operations Create Service Account Modal](https://developer.salesforce.com/docs/media/2Invite_people.png '{"class": "image-xl"}') 3. Select **Create a service account** and **Continue**. ![Agentforce Operations Create Service Account Modal](https://developer.salesforce.com/docs/media/3Create_service_account.png '{"class": "image-xl"}') 4. Configure the Service Account, and click **Create**. ![Agentforce Operations Service Account Created Modal](https://developer.salesforce.com/docs/media/4Service_account_created.png '{"class": "image-xl"}') **important:** Immediately save your service account's `clientId` and `clientSecret` credentials somewhere safe. Your credentials are only available from this screen and are never accessible again. Salesforce recommends using Keyring or a Password Manager to safely store your credentials. 5. To view and manage your workspace's service accounts, in the navigation panel, select **Admin**, click the **People** tab, and use "service-account" as the filter. **note:** You can edit a service account's details or deactivate it, but you can't view its client ID or client secret again. ## Find Your Workspace UUID Every API call requires your workspace UUID. 1. Open your Agentforce Operations workspace in a browser. 2. Open your browser's developer tools. Press **F12** (Windows) or **Command+Option+I** (Mac). 3. Click the **Network** tab. 4. Refresh the page. 5. In the filter box, type `CurrentTenantQuery`. **tip:** If `CurrentTenantQuery` doesn't appear, refresh the page again while the Network tab is open. 6. Click a `CurrentTenantQuery` request, then click the **Response** tab. 7. Copy the value of the `uuid` field. This string is your workspace UUID. ## Get an Access Token All calls to the Agentforce Operations REST API require a token. Create a token by using the client ID, the client secret, and your workspace UUID. An access token expires after 2 hours. 1. Send a POST request to the token endpoint with your service account credentials and workspace UUID. In the code sample, replace ``, ``, ``, and `` with the values for your workspace. ```bash curl -X POST \ -H 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'grant_type=client_credentials' \ --data-urlencode 'client_id=' \ --data-urlencode 'client_secret=' \ https://.regrello.salesforce.com/oauth//token ``` 2. Verify your response. A successful response looks like this: ```json { "access_token": "eyJ...(shortened)", "expires_in": 7200, "token_type": "Bearer" } ``` 3. Copy the `access_token` value to use in your API calls. **note:** Tokens expire after 2 hours. ## Call the API With your access token and workspace UUID, you're ready to call the API. 1. Call an API endpoint. Every request requires two headers: `Authorization` and `X-Regrello-Workspace-ID`. This example retrieves a list of published blueprints in your workspace. In the code sample, replace ``, ``, and `` with the values for your workspace. ```bash curl 'https://.regrello.salesforce.com/api/v1/blueprints' \ -H "Authorization: Bearer " \ -H "X-Regrello-Workspace-ID: " ``` 2. Verify the response. A successful response returns HTTP 200. In the get blueprints list example, the response body looks like this: ```json [ { "blueprintUuid": "ckuJA2XGT-Q", "description": null, "id": 2227, "name": "API Example", "numberOfStages": 1, "type": "COMPANY", "versionNumber": 1 } ] ``` **note:** Pagination details are in the `SFDC-Pagination-Offset`, `SFDC-Pagination-Limit`, `SFDC-Pagination-Total-Count`, and `SFDC-Pagination-Result-Count` response headers. ## See Also - [Agentforce Operations REST API Reference](https://developer.salesforce.com/docs/platform/agentforce-operations/references/agentforce-operations-rest)