> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/integrations/catalog/workable.md).

# Workable

Integration with Workable ATS for managing jobs, candidates, and applications.

## Connectors

Choose the connector that matches your authentication method. The options below use the names shown in StackAI.

| Connector | Authentication |
| --------- | -------------- |
| Workable  | API Key        |

### Workable

Connect to Workable ATS (Applicant Tracking System) to manage jobs, candidates, and applications.

#### Set up in Workable

1. Sign in to Workable as an Admin user.
2. Scroll to the Access Token section and click to generate a new token.
3. Give the token a name, choose an expiration, and select the scopes it should have, then create it.

#### Set up in StackAI

1. Open **Settings → Connections**, add a connection, and select **Workable**.
2. Enter the credentials and connection details in the fields below.
3. Save the connection and check its connection status. Select this saved connection when configuring an action or feature that uses it.

**Connection fields**

| StackAI field | Required | What to enter                                                                                                                                                                   |
| ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| API Key       | Yes      | Your Workable API key. You can create one in your Workable account settings > Integrations > Apps. [Provider instructions](https://workable.com/backend/settings/integrations). |
| Subdomain     | Yes      | Your Workable subdomain (the first part of your Workable URL). For example, if your URL is <https://pearly.workable.com>, your subdomain is 'pearly'.                           |

**Provider documentation:** [Setup reference](https://workable.readme.io/reference/generate-an-access-token).

### Verify the connection

Check that the connection is healthy. Then run a read operation against a resource the connected account can access. A successful connection check confirms authentication; it does not guarantee permission for every action.

If access is denied, check the credential or OAuth permissions, the selected account or environment, and access to the specific resource. Update expired credentials or reconnect after permissions change.

## Use an action

1. Add the required **Workable** action to the workflow.
2. Select a connection when the action requests one.
3. Complete the required fields. Use the reference picker when a value comes from another workflow step.
4. Run the workflow and inspect the action’s output. Check the result before using it in a later step.

## Actions

### List Jobs

List jobs from Workable ATS with optional filtering and pagination

#### Inputs

| Field          | Type     | Required | Description                                                                                                              |
| -------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------ |
| Limit          | integer  | No       | Maximum number of jobs to return (default: 50, max: 100). Default: 50.                                                   |
| State          | string   | No       | Filter jobs by state: draft, published, closed, archived (optional).                                                     |
| Since ID       | string   | No       | Retrieve jobs with IDs greater than this value (optional).                                                               |
| Max ID         | string   | No       | Retrieve jobs with IDs less than this value (optional).                                                                  |
| Created After  | datetime | No       | Retrieve jobs created after this timestamp (ISO8601 or Unix time, optional).                                             |
| Updated After  | datetime | No       | Retrieve jobs updated after this timestamp (ISO8601 or Unix time, optional).                                             |
| Include Fields | string   | No       | Comma-separated list of additional fields to include: description, full\_description, requirements, benefits (optional). |

#### Outputs

| Field            | Type          | Description                                                              |
| ---------------- | ------------- | ------------------------------------------------------------------------ |
| Jobs (Complete)  | object\_array | Complete list of jobs from the Workable API response.                    |
| Paging           | object        | Pagination information including next page URL if available.             |
| Job Titles       | string        | JSON array of all job titles from the results.                           |
| Job Shortcodes   | string        | JSON array of all job shortcodes from the results.                       |
| Departments      | string        | JSON array of all departments from the results.                          |
| Locations        | string        | JSON array of all job locations from the results.                        |
| Job States       | string        | JSON array of all job states from the results.                           |
| Job IDs          | string        | JSON array of all job IDs from the results.                              |
| Created Dates    | string        | JSON array of all job creation dates (formatted as YYYY-MM-DD HH:MM:SS). |
| Updated Dates    | string        | JSON array of all job update dates (formatted as YYYY-MM-DD HH:MM:SS).   |
| Job URLs         | string        | JSON array of all job URLs from the results.                             |
| Application URLs | string        | JSON array of all application URLs from the results.                     |
| Total Count      | number        | Total number of jobs returned.                                           |

### Get Job

Get detailed information about a specific job by shortcode

#### Inputs

| Field         | Type   | Required | Description                                                           |
| ------------- | ------ | -------- | --------------------------------------------------------------------- |
| Job Shortcode | string | Yes      | The shortcode of the job to retrieve (e.g., '3CD525EF9E'). Default: . |

#### Outputs

| Field            | Type     | Description                                                        |
| ---------------- | -------- | ------------------------------------------------------------------ |
| Job (Complete)   | object   | Complete job details from the Workable API response.               |
| Job ID           | string   | The unique identifier of the job.                                  |
| Job Shortcode    | string   | The shortcode of the job (e.g., '3CD525EF9E').                     |
| Job Title        | string   | The title of the job position.                                     |
| Department       | string   | The department this job belongs to.                                |
| Location         | string   | The location/city of the job.                                      |
| Job State        | string   | The current state of the job (draft, published, closed, archived). |
| Created At       | datetime | When the job was created (formatted as YYYY-MM-DD HH:MM:SS).       |
| Updated At       | datetime | When the job was last updated (formatted as YYYY-MM-DD HH:MM:SS).  |
| Job URL          | string   | The public URL to view the job posting.                            |
| Application URL  | string   | The URL where candidates can apply for this job.                   |
| Full Description | string   | The complete job description including all details.                |
| Requirements     | string   | The job requirements and qualifications.                           |
| Benefits         | string   | The benefits and perks offered with this job.                      |

### Search Jobs

Search for jobs in Workable with optional filtering

#### Inputs

| Field          | Type    | Required | Description                                                                                                              |
| -------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------ |
| Search Query   | string  | No       | Search query to filter jobs by title, description, or other fields (optional).                                           |
| State          | string  | No       | Filter jobs by state: draft, published, closed, archived (optional).                                                     |
| Limit          | integer | No       | Maximum number of jobs to return (default: 50, max: 100). Default: 50.                                                   |
| Include Fields | string  | No       | Comma-separated list of additional fields to include: description, full\_description, requirements, benefits (optional). |

#### Outputs

| Field           | Type          | Description                                                  |
| --------------- | ------------- | ------------------------------------------------------------ |
| Jobs (Complete) | object\_array | Complete list of jobs from the Workable API response.        |
| Paging          | object        | Pagination information including next page URL if available. |
| Job Titles      | string        | JSON array of all job titles from the results.               |
| Job Shortcodes  | string        | JSON array of all job shortcodes from the results.           |
| Departments     | string        | JSON array of all departments from the results.              |
| Locations       | string        | JSON array of all job locations from the results.            |
| Job States      | string        | JSON array of all job states from the results.               |
| Total Count     | number        | Total number of jobs returned.                               |

### Get Job Activities

Get activities/history for a specific job by shortcode

#### Inputs

| Field         | Type   | Required | Description                                                                     |
| ------------- | ------ | -------- | ------------------------------------------------------------------------------- |
| Job Shortcode | string | Yes      | The shortcode of the job to get activities for (e.g., '3CD525EF9E'). Default: . |

#### Outputs

| Field                 | Type          | Description                                                                   |
| --------------------- | ------------- | ----------------------------------------------------------------------------- |
| Activities (Complete) | object\_array | Complete list of job activities from the Workable API response.               |
| Activity Types        | string        | JSON array of all activity types from the results.                            |
| Activity Descriptions | string        | JSON array of all activity descriptions from the results.                     |
| Activity Users        | string        | JSON array of all users who performed activities.                             |
| Activity Dates        | string        | JSON array of all activity creation dates (formatted as YYYY-MM-DD HH:MM:SS). |
| Total Activities      | number        | Total number of activities returned.                                          |

### Get Job Application Form

Get application form configuration for a specific job by shortcode

#### Inputs

| Field         | Type   | Required | Description                                                                           |
| ------------- | ------ | -------- | ------------------------------------------------------------------------------------- |
| Job Shortcode | string | Yes      | The shortcode of the job to get application form for (e.g., '3CD525EF9E'). Default: . |

#### Outputs

| Field                       | Type   | Description                                                             |
| --------------------------- | ------ | ----------------------------------------------------------------------- |
| Application Form (Complete) | object | Complete application form configuration from the Workable API response. |
| Form Fields                 | string | JSON array of all form field names from the application form.           |
| Field Types                 | string | JSON array of all field types from the application form.                |
| Required Fields             | string | JSON array of all required field names from the application form.       |
| Optional Fields             | string | JSON array of all optional field names from the application form.       |
| Total Fields                | number | Total number of form fields.                                            |
| Required Fields Count       | number | Number of required fields.                                              |

### Get Job Questions

Get interview questions for a specific job by shortcode

#### Inputs

| Field         | Type   | Required | Description                                                                    |
| ------------- | ------ | -------- | ------------------------------------------------------------------------------ |
| Job Shortcode | string | Yes      | The shortcode of the job to get questions for (e.g., '3CD525EF9E'). Default: . |

#### Outputs

| Field                    | Type          | Description                                                    |
| ------------------------ | ------------- | -------------------------------------------------------------- |
| Questions (Complete)     | object\_array | Complete list of job questions from the Workable API response. |
| Question Texts           | string        | JSON array of all question texts from the results.             |
| Question Types           | string        | JSON array of all question types from the results.             |
| Question IDs             | string        | JSON array of all question IDs from the results.               |
| Required Questions       | string        | JSON array indicating which questions are required.            |
| Total Questions          | number        | Total number of questions returned.                            |
| Required Questions Count | number        | Number of required questions.                                  |

### Get Job Stages

Get hiring stages/pipeline for a specific job by shortcode

#### Inputs

| Field         | Type   | Required | Description                                                                 |
| ------------- | ------ | -------- | --------------------------------------------------------------------------- |
| Job Shortcode | string | Yes      | The shortcode of the job to get stages for (e.g., '3CD525EF9E'). Default: . |

#### Outputs

| Field             | Type          | Description                                                 |
| ----------------- | ------------- | ----------------------------------------------------------- |
| Stages (Complete) | object\_array | Complete list of job stages from the Workable API response. |
| Stage Names       | string        | JSON array of all stage names from the results.             |
| Stage IDs         | string        | JSON array of all stage IDs from the results.               |
| Stage Positions   | string        | JSON array of all stage positions/order from the results.   |
| Stage Types       | string        | JSON array of all stage types from the results.             |
| Total Stages      | number        | Total number of stages returned.                            |

### Get Job Custom Attributes

Get custom attributes for a specific job by shortcode

#### Inputs

| Field         | Type   | Required | Description                                                                            |
| ------------- | ------ | -------- | -------------------------------------------------------------------------------------- |
| Job Shortcode | string | Yes      | The shortcode of the job to get custom attributes for (e.g., '3CD525EF9E'). Default: . |

#### Outputs

| Field                        | Type          | Description                                                            |
| ---------------------------- | ------------- | ---------------------------------------------------------------------- |
| Custom Attributes (Complete) | object\_array | Complete list of job custom attributes from the Workable API response. |
| Attribute Names              | string        | JSON array of all custom attribute names from the results.             |
| Attribute Values             | string        | JSON array of all custom attribute values from the results.            |
| Attribute Types              | string        | JSON array of all custom attribute types from the results.             |
| Attribute IDs                | string        | JSON array of all custom attribute IDs from the results.               |
| Total Attributes             | number        | Total number of custom attributes returned.                            |

### Get Job Members

Get team members assigned to a specific job by shortcode

#### Inputs

| Field         | Type   | Required | Description                                                                  |
| ------------- | ------ | -------- | ---------------------------------------------------------------------------- |
| Job Shortcode | string | Yes      | The shortcode of the job to get members for (e.g., '3CD525EF9E'). Default: . |

#### Outputs

| Field              | Type          | Description                                                  |
| ------------------ | ------------- | ------------------------------------------------------------ |
| Members (Complete) | object\_array | Complete list of job members from the Workable API response. |
| Member Names       | string        | JSON array of all member names from the results.             |
| Member Emails      | string        | JSON array of all member email addresses from the results.   |
| Member Roles       | string        | JSON array of all member roles from the results.             |
| Member IDs         | string        | JSON array of all member IDs from the results.               |
| Total Members      | number        | Total number of members returned.                            |

### Get Job Recruiters

Get recruiters assigned to a specific job by shortcode

#### Inputs

| Field         | Type   | Required | Description                                                                     |
| ------------- | ------ | -------- | ------------------------------------------------------------------------------- |
| Job Shortcode | string | Yes      | The shortcode of the job to get recruiters for (e.g., '3CD525EF9E'). Default: . |

#### Outputs

| Field                 | Type          | Description                                                     |
| --------------------- | ------------- | --------------------------------------------------------------- |
| Recruiters (Complete) | object\_array | Complete list of job recruiters from the Workable API response. |
| Recruiter Names       | string        | JSON array of all recruiter names from the results.             |
| Recruiter Emails      | string        | JSON array of all recruiter email addresses from the results.   |
| Recruiter Roles       | string        | JSON array of all recruiter roles from the results.             |
| Recruiter IDs         | string        | JSON array of all recruiter IDs from the results.               |
| Total Recruiters      | number        | Total number of recruiters returned.                            |

### Add Comments

Add comments to a candidate's timeline in Workable.

#### Inputs

| Field        | Type                      | Required | Description                                                                                                                                                             |
| ------------ | ------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Candidate ID | string                    | Yes      | The ID of the candidate to add a comment to. Default: .                                                                                                                 |
| Member ID    | string                    | Yes      | The ID of the member who is adding the comment. Default: .                                                                                                              |
| Comment      | string                    | Yes      | The comment to add to the candidate's timeline. Default: .                                                                                                              |
| Policy       | multiple\_select (string) | Yes      | The policy to add to the candidate's timeline. Available values: Admin, Recruiting Admin, Hiring Manager, Simple (Standard Members), Reviewer, Recruiter. Default: \[]. |

#### Outputs

| Field      | Type   | Description                           |
| ---------- | ------ | ------------------------------------- |
| Comment ID | string | The ID of the comment that was added. |
| Response   | string | The response from the API call.       |

### Move Candidate

Move a candidate to a new stage in Workable.

#### Inputs

| Field        | Type   | Required | Description                                                  |
| ------------ | ------ | -------- | ------------------------------------------------------------ |
| Candidate ID | string | Yes      | The ID of the candidate to move. Default: .                  |
| Member ID    | string | Yes      | The ID of the member who is moving the candidate. Default: . |
| Stage        | string | Yes      | The stage to move the candidate to. Default: .               |

#### Outputs

| Field    | Type   | Description                     |
| -------- | ------ | ------------------------------- |
| Response | string | The response from the API call. |

### Get Candidate

Get a candidate from Workable.

#### Inputs

| Field        | Type   | Required | Description                     |
| ------------ | ------ | -------- | ------------------------------- |
| Candidate ID | string | Yes      | The ID of the candidate to get. |

#### Outputs

| Field                | Type     | Description                                        |
| -------------------- | -------- | -------------------------------------------------- |
| Candidate ID         | string   | The ID of the candidate.                           |
| Candidate Name       | string   | The name of the candidate.                         |
| Candidate First Name | string   | The first name of the candidate.                   |
| Candidate Last Name  | string   | The last name of the candidate.                    |
| Candidate Headline   | string   | The headline of the candidate.                     |
| Job Title            | string   | The title of the job the candidate applied to.     |
| Job Shortcode        | string   | The shortcode of the job the candidate applied to. |
| Stage                | string   | The stage of the candidate.                        |
| Profile URL          | string   | The URL of the candidate's profile.                |
| Email                | string   | The email of the candidate.                        |
| Created At           | datetime | The date and time the candidate was created.       |
| Resume URL           | string   | The URL of the candidate's resume.                 |

### Get Candidate Comments

Get comments from a candidate's timeline in Workable.

#### Inputs

| Field        | Type   | Required | Description                                                    |
| ------------ | ------ | -------- | -------------------------------------------------------------- |
| Candidate ID | string | Yes      | The ID of the candidate whose comments to retrieve. Default: . |

#### Outputs

| Field               | Type          | Description                                                 |
| ------------------- | ------------- | ----------------------------------------------------------- |
| Comments (Complete) | object\_array | Complete list of comments on the candidate's timeline.      |
| Comment Bodies      | string        | JSON array of all comment body texts.                       |
| Comment Authors     | string        | JSON array of the names of members who posted each comment. |
| Comment Dates       | string        | JSON array of comment creation timestamps (ISO 8601).       |
| Total Comments      | number        | Total number of comments returned.                          |

### List Candidates

List candidates from Workable.

#### Inputs

| Field         | Type     | Required | Description                                                                  |
| ------------- | -------- | -------- | ---------------------------------------------------------------------------- |
| Limit         | integer  | No       | Maximum number of candidates to return (default: 50, max: 100). Default: 50. |
| Email         | string   | No       | Email of the candidate to list. Default: .                                   |
| Job Shortcode | string   | No       | Shortcode of the job to list candidates for. Default: .                      |
| Stage         | string   | No       | Stage of the candidate to list. Default: .                                   |
| Created After | datetime | No       | Candidates created after this date and time.                                 |
| Updated After | datetime | No       | Candidates updated after this date and time.                                 |
| Since ID      | string   | No       | Candidates with IDs greater than this value. Default: .                      |
| Max ID        | string   | No       | Candidates with IDs less than this value. Default: .                         |

#### Outputs

| Field      | Type          | Description         |
| ---------- | ------------- | ------------------- |
| Candidates | object\_array | List of candidates. |

## Triggers

A trigger starts a workflow when its configured event occurs. Configure the event and filters before enabling the trigger.

### On Candidate Moved

Trigger a workflow execution when a new candidate is moved in Workable.

#### Configuration

| Field | Type            | Required | Description                                                                                                                                                                                     |
| ----- | --------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Job   | select (string) | No       | Select the Workable job to listen for candidates, or enter a job shortcode directly. Select 'All Jobs' to listen across all jobs. Options load from the selected connection. Default: all-jobs. |
| Stage | select (string) | No       | The stage to listen for candidates. If not provided, all stages will be listened for. Options load from the selected connection. Default: all-stages.                                           |

#### Event inputs

| Field                   | Type     | Required | Description                                                    |
| ----------------------- | -------- | -------- | -------------------------------------------------------------- |
| Event ID                | string   | No       | The ID of the event that triggered the webhook.                |
| Fired At                | datetime | No       | The time at which the event was fired.                         |
| Candidate ID            | string   | No       | The ID of the candidate in Workable.                           |
| Candidate Full Name     | string   | No       | The fullname of the candidate in Workable.                     |
| Candidate First Name    | string   | No       | The first name of the candidate in Workable.                   |
| Candidate Last Name     | string   | No       | The last name of the candidate in Workable.                    |
| Candidate Profile URL   | string   | No       | The profile URL of the candidate in Workable.                  |
| Candidate Headline      | string   | No       | The headline of the candidate in Workable.                     |
| Candidate Email         | string   | No       | The email of the candidate in Workable.                        |
| Candidate Created At    | datetime | No       | The creation date of the candidate in Workable.                |
| Candidate Resume URL    | string   | No       | The URL of the candidate's resume in Workable.                 |
| Candidate Job Title     | string   | No       | The job title of the candidate in Workable.                    |
| Candidate Job Shortcode | string   | No       | The shortcode of the job the candidate applied to in Workable. |
| Candidate Stage         | string   | No       | The stage of the candidate in Workable.                        |
| Event Type              | string   | No       | The type of event that triggered the webhook.                  |

#### Outputs

| Field                   | Type     | Description                                                    |
| ----------------------- | -------- | -------------------------------------------------------------- |
| Candidate ID            | string   | The ID of the candidate in Workable.                           |
| Candidate Full Name     | string   | The fullname of the candidate in Workable.                     |
| Candidate First Name    | string   | The first name of the candidate in Workable.                   |
| Candidate Last Name     | string   | The last name of the candidate in Workable.                    |
| Candidate Profile URL   | string   | The profile URL of the candidate in Workable.                  |
| Candidate Headline      | string   | The headline of the candidate in Workable.                     |
| Candidate Email         | string   | The email of the candidate in Workable.                        |
| Candidate Created At    | datetime | The creation date of the candidate in Workable.                |
| Candidate Resume URL    | string   | The URL of the candidate's resume in Workable.                 |
| Candidate Job Title     | string   | The job title of the candidate in Workable.                    |
| Candidate Job Shortcode | string   | The shortcode of the job the candidate applied to in Workable. |
| Candidate Stage         | string   | The stage of the candidate in Workable.                        |
| Fired At                | datetime | The time at which the event was fired.                         |

### On Candidate Created

Trigger a workflow execution when a new candidate is created in Workable.

#### Configuration

| Field | Type            | Required | Description                                                                                                                                                                                     |
| ----- | --------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Job   | select (string) | No       | Select the Workable job to listen for candidates, or enter a job shortcode directly. Select 'All Jobs' to listen across all jobs. Options load from the selected connection. Default: all-jobs. |
| Stage | select (string) | No       | The stage to listen for candidates. If not provided, all stages will be listened for. Options load from the selected connection. Default: all-stages.                                           |

#### Event inputs

| Field                   | Type     | Required | Description                                                    |
| ----------------------- | -------- | -------- | -------------------------------------------------------------- |
| Event ID                | string   | No       | The ID of the event that triggered the webhook.                |
| Fired At                | datetime | No       | The time at which the event was fired.                         |
| Candidate ID            | string   | No       | The ID of the candidate in Workable.                           |
| Candidate Full Name     | string   | No       | The fullname of the candidate in Workable.                     |
| Candidate First Name    | string   | No       | The first name of the candidate in Workable.                   |
| Candidate Last Name     | string   | No       | The last name of the candidate in Workable.                    |
| Candidate Profile URL   | string   | No       | The profile URL of the candidate in Workable.                  |
| Candidate Headline      | string   | No       | The headline of the candidate in Workable.                     |
| Candidate Email         | string   | No       | The email of the candidate in Workable.                        |
| Candidate Created At    | datetime | No       | The creation date of the candidate in Workable.                |
| Candidate Resume URL    | string   | No       | The URL of the candidate's resume in Workable.                 |
| Candidate Job Title     | string   | No       | The job title of the candidate in Workable.                    |
| Candidate Job Shortcode | string   | No       | The shortcode of the job the candidate applied to in Workable. |
| Candidate Stage         | string   | No       | The stage of the candidate in Workable.                        |
| Event Type              | string   | No       | The type of event that triggered the webhook.                  |

#### Outputs

| Field                   | Type     | Description                                                    |
| ----------------------- | -------- | -------------------------------------------------------------- |
| Candidate ID            | string   | The ID of the candidate in Workable.                           |
| Candidate Full Name     | string   | The fullname of the candidate in Workable.                     |
| Candidate First Name    | string   | The first name of the candidate in Workable.                   |
| Candidate Last Name     | string   | The last name of the candidate in Workable.                    |
| Candidate Profile URL   | string   | The profile URL of the candidate in Workable.                  |
| Candidate Headline      | string   | The headline of the candidate in Workable.                     |
| Candidate Email         | string   | The email of the candidate in Workable.                        |
| Candidate Created At    | datetime | The creation date of the candidate in Workable.                |
| Candidate Resume URL    | string   | The URL of the candidate's resume in Workable.                 |
| Candidate Job Title     | string   | The job title of the candidate in Workable.                    |
| Candidate Job Shortcode | string   | The shortcode of the job the candidate applied to in Workable. |
| Candidate Stage         | string   | The stage of the candidate in Workable.                        |
| Fired At                | datetime | The time at which the event was fired.                         |

## Important behavior

Actions that create, update, send, or delete data can change the connected service. Review their inputs before running them. A retry can repeat an operation; consider this when configuring retries for actions that change data.

The catalog lists the fields and capabilities available in the supplied provider definition. Availability can also depend on your deployment and organization’s Feature Access settings.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.stackai.com/integrations/catalog/workable.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
