> For the complete documentation index, see [llms.txt](https://docs.usepylon.com/pylon-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.usepylon.com/pylon-docs/developer/api/conventions.md).

# API conventions

How Pylon's API handles IDs, timestamps, pagination, search filters, updates, files, and slugs

These rules apply across Pylon's API. The [API reference](https://docs.usepylon.com/pylon-docs/developer/api/api-reference.md) lists each endpoint's parameters; this page explains how they behave.

## Requests and responses

* Send request bodies as JSON with `Content-Type: application/json`. The one exception is [`POST /attachments`](https://docs.usepylon.com/pylon-docs/developer/api/conventions.md#upload-a-file), which takes `multipart/form-data`.
* JSON request bodies are generally limited to 10 MiB. If the body exceeds the limit, the API returns HTTP `413` with code `payload_too_large`. File uploads and inbound webhooks have separate limits.
* Successful responses put the result in `data` and include a `request_id`. List and search responses also include `pagination`.
* Unknown fields are ignored, not rejected. A misspelled field name is silently dropped, so check the field names in the reference.
* Sending `null` for an optional field is the same as leaving it out.

## IDs

Most endpoints take Pylon IDs. A few path parameters also accept another identifier:

| Path                                                            | Accepts                           |
| --------------------------------------------------------------- | --------------------------------- |
| `/issues/{id}` and its sub-paths                                | Issue ID or issue number          |
| `/accounts/{id}`, and account activities, highlights, and files | Account ID or account external ID |
| `/contacts/{id}`                                                | Contact ID or contact external ID |

See [External IDs](https://docs.usepylon.com/pylon-docs/developer/api/external-ids.md) for attaching your own identifiers to accounts.

## Timestamps

* Every timestamp uses [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339), for example `2026-10-01T00:00:00Z` or `2026-10-01T09:00:00+02:00`. A timezone (`Z` or an offset) is required.
* Responses return timestamps in UTC to the second, for example `2026-10-01T14:03:27Z`.
* In query strings, encode `+` as `%2B` or use `Z`. An unencoded `+` is read as a space, and the request fails with `400`.

## Pagination

List and search endpoints use cursor pagination.

1. Send a `limit` (optional). Leave out `cursor` for the first page.
2. If the response has `pagination.has_next_page: true`, send `pagination.cursor` as `cursor` in the next request, with the same filter and other parameters.
3. Stop when `pagination` is missing or `has_next_page` is `false`.

`GET` endpoints take `cursor` and `limit` as query parameters. `POST .../search` endpoints take them in the JSON body. Treat cursors as opaque.

Limits vary by endpoint and are listed on each endpoint's `limit` parameter. Most search endpoints default to 100 results and accept up to 1,000. `GET /issues` defaults to and allows up to 20,000.

## Listing issues by time

[`GET /issues`](https://docs.usepylon.com/pylon-docs/developer/api/api-reference/issues.md) requires a time window:

| Question                  | Answer                                              |
| ------------------------- | --------------------------------------------------- |
| Which field is filtered?  | The issue's `created_at`.                           |
| Are the bounds inclusive? | `start_time` is inclusive. `end_time` is exclusive. |
| Are both required?        | Yes. Leaving either out returns `400`.              |
| Maximum window            | 365 days between `start_time` and `end_time`.       |
| Order                     | Newest `created_at` first.                          |
| Page size                 | `limit` defaults to 20,000, the maximum.            |

```bash
curl "https://api.usepylon.com/issues?start_time=2026-09-01T00:00:00Z&end_time=2026-10-01T00:00:00Z" \
  -H "Authorization: Bearer $PYLON_API_TOKEN"
```

To filter on another timestamp, such as `updated_at`, `resolved_at`, or `latest_message_activity_at`, use [`POST /issues/search`](https://docs.usepylon.com/pylon-docs/developer/api/api-reference/issues.md). Search has no maximum window:

```json
{
  "filter": {
    "field": "updated_at",
    "operator": "time_range",
    "values": ["2026-09-01T00:00:00Z", "2026-10-01T00:00:00Z"]
  }
}
```

## Search filters

Every `POST .../search` endpoint except feature requests takes a `filter` object with the same structure.

| Key              | Use                                                                                                                                                                                      |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `operator`       | Required unless the filter sets `related_object`. See the operators below.                                                                                                               |
| `field`          | The field to compare. Required unless `operator` is `and`, `or`, or `not`.                                                                                                               |
| `value`          | A single value, for operators that take one.                                                                                                                                             |
| `values`         | An array, for operators that take several.                                                                                                                                               |
| `subfilters`     | An array of filters. Only used with `and`, `or`, and `not`.                                                                                                                              |
| `related_object` | Matches on a related object, such as an issue's account. See [Filter on a related object](https://docs.usepylon.com/pylon-docs/developer/api/conventions.md#filter-on-a-related-object). |

Combine conditions with `and` and `or`:

```json
{
  "filter": {
    "operator": "and",
    "subfilters": [
      { "field": "state", "operator": "in", "values": ["new", "waiting_on_you"] },
      {
        "operator": "or",
        "subfilters": [
          { "field": "tags", "operator": "contains", "value": "billing" },
          { "field": "priority", "operator": "equals", "value": "urgent" }
        ]
      }
    ]
  },
  "limit": 100
}
```

* A filter can be at most **5 levels deep**, counting the top-level filter. The example above uses 3.
* In the example, `priority` is a custom field slug. Custom fields are filtered by slug, like built-in fields.
* `and` and `or` must have `subfilters` and can't have a `field` or `value`.
* `not` matches records that don't match its subfilter. It takes exactly one subfilter and no `field` or `value`; to negate several conditions, wrap them in one `and` or `or`. Only [`POST /issues/search`](https://docs.usepylon.com/pylon-docs/developer/api/api-reference/issues.md) accepts `not`; other endpoints return `400`.
* Use `value` or `values` according to the operator. Sending the other one returns `400`.

### Filter on a related object

To match on a field of a related object, such as an issue's account or requester, put a `related_object` in place of a condition. `relationship` names the related object and `filter` is the condition it must match:

```json
{
  "filter": {
    "operator": "and",
    "subfilters": [
      { "field": "state", "operator": "equals", "value": "new" },
      {
        "related_object": {
          "relationship": "account",
          "filter": { "field": "name", "operator": "equals", "value": "Acme" }
        }
      }
    ]
  }
}
```

| Endpoint                | Relationship | Related object | Requires             |
| ----------------------- | ------------ | -------------- | -------------------- |
| `POST /issues/search`   | `account`    | Account        | Account read         |
|                         | `requester`  | Contact        | Contact read         |
|                         | `assignee`   | User           | User read            |
| `POST /contacts/search` | `account`    | Account        | Account read         |
| `POST /accounts/search` | `owner`      | User           | User read            |
| `POST /tasks/search`    | `account`    | Account        | Account read         |
|                         | `project`    | Project        | Task management read |
|                         | `assignee`   | User           | User read            |
| `POST /projects/search` | `account`    | Account        | Account read         |

* A filter with `related_object` sets nothing else: no `operator`, `field`, `value`, `values`, or `subfilters`.
* `related_object.filter` uses the fields, operators, and custom field slugs of the related object's own search endpoint, listed in [Allowed fields](https://docs.usepylon.com/pylon-docs/developer/api/conventions.md#allowed-fields). Every one of those fields works, including account `account_id` and `tags`. Project `is_archived` takes `true` or `false`.
* To check several conditions on the same related object, make `related_object.filter` an `and` or `or` group.
* A `related_object` can't contain another `related_object`. It doesn't count toward the depth limit.
* Each relationship needs the read permission of the related object, without restrictions. Without it, the request returns `403`.
* Dotted paths such as `account.name` aren't supported. The error message shows the `related_object` form to use instead.
* Ticket form visibility conditions (`fields[].visibility_conditions[].filter` from `GET /ticket-forms`) use this format, and can contain `related_object` with the issue relationships `account`, `requester`, and `assignee`. A condition that hops through a relationship custom field to an account, contact, or user reads back as a `related_object` with `custom_field` (the field's slug) in place of `relationship`, and its `filter` uses the target object's fields and custom field slugs. A condition this format can't express, such as a hop to a custom object, a chain of hops, or a value relative to the viewer, has `filter_unsupported: true` and no `filter`.
* Search filters don't accept `related_object.custom_field` yet and return `400`. Filter on the relationship custom field's slug with the related objects' IDs instead.

### Operators

| Operator                                                                     | Takes                    | Matches when the field...                                        |
| ---------------------------------------------------------------------------- | ------------------------ | ---------------------------------------------------------------- |
| `equals` / `not_equals`                                                      | `value`                  | is / isn't exactly the value                                     |
| `in` / `not_in`                                                              | `values`                 | is / isn't one of the values                                     |
| `contains` / `does_not_contain`                                              | `value`                  | has / doesn't have the value (multi-value fields such as `tags`) |
| `includes_all_of`                                                            | `values`                 | has every value (multi-value fields)                             |
| `includes_exactly`                                                           | `values`                 | has exactly the values, in any order (multi-value fields)        |
| `belongs_to` / `not_belongs_to`                                              | `values` (team IDs)      | is / isn't a user in any of the teams, including subteams        |
| `string_contains` / `string_does_not_contain`                                | `value`                  | contains / doesn't contain the text                              |
| `starts_with` / `ends_with`                                                  | `value`                  | starts / ends with the text                                      |
| `time_is_after` / `time_is_before`                                           | `value` (RFC 3339)       | is strictly after / before the time                              |
| `time_range`                                                                 | `values`: `[start, end]` | is between the two times, including both ends                    |
| `time_is_in_last` / `time_is_not_in_last`                                    | `value` (`"<N>,<unit>"`) | is / is set and isn't between the start of the window and now    |
| `time_is_in_next` / `time_is_not_in_next`                                    | `value` (`"<N>,<unit>"`) | is / is set and isn't between now and the end of the window      |
| `greater_than`, `greater_than_or_equals`, `less_than`, `less_than_or_equals` | `value`                  | compares numerically                                             |
| `is_set` / `is_unset`                                                        | nothing                  | has / doesn't have a value                                       |

* `contains` and `does_not_contain` on a text field that holds one value, such as issue `subject` and `body_html`, account `name`, or contact `email` and `name`, mean `string_contains` and `string_does_not_contain`. On account `name`, `does_not_contain` still excludes an exact name.
* `belongs_to` and `not_belongs_to` work on issue `assignee_id`, account `owner_id`, and User custom fields. They take team IDs only, not `current_user` or `my_teams`. `not_belongs_to` also matches records with no user.
* `includes_exactly` works on issue `tags` and Multi-select custom fields.
* Relative time operators take `"<N>,<unit>"`, where unit is `milliseconds`, `seconds`, `days`, or `months`, such as `"7,days"`. Days and months are calendar-aligned: `"7,days"` starts at midnight seven days ago. They use UTC unless a third part names an IANA time zone, such as `"7,days,America/New_York"`. Any other value returns `400`.
* `time_is_in_last` and `time_is_not_in_last` work on the built-in timestamp fields of issue, account, project, milestone, and call recording search. Task and custom object timestamps, and Date and Datetime custom fields, also accept `time_is_in_next` and `time_is_not_in_next`.

### Allowed fields

Each search endpoint accepts its own fields, and each field allows only some operators. The full field-and-operator table is in the endpoint's description in the API reference. An invalid filter, such as one with an unknown field or a disallowed operator, returns `400` with code `invalid_filter`. The response lists every problem in the filter, each with its location and, where possible, the closest valid field, operator, or value. See [Filter errors](https://docs.usepylon.com/pylon-docs/developer/api/errors.md#filter-errors).

| Endpoint                             | Built-in fields                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Custom fields | `search_text` |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ------------- |
| `POST /issues/search`                | `created_at`, `updated_at`, `resolved_at`, `latest_message_activity_at`, `latest_customer_message_activity_at`, `latest_vendor_message_activity_at`, `first_response_at`, `state`, `tags`, `subject`, `body_html`, `number`, `source`, `number_of_touches`, `account_id`, `partner_account_id`, `requester_id`, `assignee_id`, `team_id`, `follower_user_id`, `follower_contact_id`, `ticket_form_id`, `issue_type`, `issue_is_issue_group`, `parent_issue_group_id`, `customer_portal_visible`, `reopened`, `slack_channel_id`, `workspace_email`, `requester_email`, `is_snoozed`, `email_subject`, `first_message_from`, `last_message_from`, `latest_public_message_activity_at`, `number_of_customer_messages`, `message_redaction_used`, `time_to_first_response`, `from_email`, `cc_email`, `ccs`, `asana_product_issue`, `github_product_issue`, `jira_product_issue`, `linear_product_issue`, `shortcut_product_issue`, `product_issue_source`, `product_ticket_completion`, `number_of_child_issues`, `created_in_channel_id`, `product_area` | Yes           | Yes           |
| `POST /accounts/search`              | `account_id`, `name`, `domains`, `primary_domain`, `tags`, `external_ids`, `owner_id`, `parent_account_id`, `partner_account_id`, `state`, `type`, `source`, `created_at`, `last_customer_activity_at`, `last_vendor_activity_at`, `last_broadcast_sent_at`, `issue_count_last_90_days`, `number_of_users_in_channel`, `primary_channel_id`, `external_channel_ids`, `external_channel_type`, `internal_channel_ids`, `slack_channel_id`, `slack_channel_name`, `internal_slack_channel_id`, `internal_slack_channel_name`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Yes           | Yes           |
| `POST /contacts/search`              | `id`, `email`, `name`, `account_id`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Yes           | Yes           |
| `POST /users/search`                 | `email` (`equals`, `in`, `not_in`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | No            | No            |
| `POST /custom-objects/{type}/search` | `name`, `account`, `created_at`, `updated_at`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Yes           | No            |
| `POST /tasks/search`                 | `account_id`, `project_id`, `status`, `assignee_id`, `milestone_id`, `created_at`, `due_date`, `updated_at`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Yes           | No            |
| `POST /projects/search`              | `account_id`, `status`, `owner_id`, `is_archived`, `created_at`, `updated_at`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Yes           | No            |
| `POST /milestones/search`            | `project_id`, `account_id`, `due_date`, `created_at`, `updated_at`, `started_at`, `completed_at`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | No            | No            |
| `POST /call-recordings/search`       | `account_id`, `source`, `title`, `start_time`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | No            | No            |
| `POST /surveys/search`               | `updated_at`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | No            | No            |
| `POST /audit-logs/search`            | `action`, `action_happened_at`, `object_id`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | No            | No            |

[`POST /feature-requests/search`](https://docs.usepylon.com/pylon-docs/developer/api/api-reference/feature-requests.md) doesn't take a `filter`. It takes `query`, `request_statuses`, `account_ids`, and `limit`.

Some fields also accept an earlier name: account `id` for `account_id`, and issue `title` for `subject`. Responses and error messages use the current names.

`search_text` runs a fuzzy text search. When you also send a `filter`, results must match both.

### Values to use

* **`state`:** `new`, `waiting_on_you`, `waiting_on_customer`, `on_hold`, `closed`, or a custom status slug.
* **`tags`:** the tag name or ID.
* **`is_snoozed`:** `true` or `false`.
* **`requester_email`:** the requester's email address. It's shorthand for a `related_object` filter on the `requester` relationship's `email`, and works for issues from any channel.
* **Fields with a fixed set of values**, such as account `state`, reject any other value with `400`, and the error lists the allowed values.
* **`current_user` and `my_teams`:** on a field that holds user IDs, such as issue `assignee_id` or account `owner_id`, `current_user` means the API token's user. On a field that holds team IDs, such as issue `team_id`, `my_teams` means that user's teams. Using either on a field that holds a different kind of ID returns `400`. `current_contact` isn't available, because API requests act as a user, not a contact.
* **Custom fields:** set `field` to the field's slug. For select and multi-select fields, use option slugs as values. See [Find slugs](https://docs.usepylon.com/pylon-docs/developer/api/conventions.md#find-slugs).

Operators for a custom field depend on its type:

| Custom field type                 | Operators                                                                                                                                                                                         |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Text, URL, Email, Select          | `equals`, `not_equals`, `in`, `not_in`, `string_contains`, `string_does_not_contain`, `starts_with`, `ends_with`, `is_set`, `is_unset`                                                            |
| Number                            | `equals`, `not_equals`, `in`, `not_in`, `greater_than`, `greater_than_or_equals`, `less_than`, `less_than_or_equals`, `is_set`, `is_unset`                                                        |
| Date, Datetime                    | `equals`, `not_equals`, `in`, `not_in`, `time_is_after`, `time_is_before`, `time_range`, `time_is_in_last`, `time_is_not_in_last`, `time_is_in_next`, `time_is_not_in_next`, `is_set`, `is_unset` |
| Multi-select                      | `contains`, `does_not_contain`, `in`, `not_in`, `includes_all_of`, `includes_exactly`, `is_set`, `is_unset`                                                                                       |
| True/False, Contact, Relationship | `equals`, `not_equals`, `in`, `not_in`, `is_set`, `is_unset`                                                                                                                                      |
| User                              | `equals`, `not_equals`, `in`, `not_in`, `belongs_to`, `not_belongs_to`, `is_set`, `is_unset`                                                                                                      |

## Updating records

`PATCH` endpoints change only the fields you send.

* **Omitted fields don't change.** `null` counts as omitted.
* **Arrays replace the whole list.** Send the complete list you want, not just additions. Send `[]` to clear it. Tags are the exception when you set `tags_apply_mode`, below.
* **Clear a reference with an empty string.** For example, `"assignee_id": ""` unassigns an issue.
* **`custom_fields` updates only the fields you list.** Other custom fields keep their values. For a multi-select field, `values` replaces the current selection. To clear a field, send its `slug` with no `value` or `values`.

| Endpoint                                            | Field                                     | Behavior                                                                                                                                         |
| --------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `PATCH /issues/{id}`                                | `tags`                                    | Replaces all tags on the issue by default. Set `tags_apply_mode` to `append_only` or `remove_only` to only add or only remove the tags you send. |
|                                                     | `assignee_id`, `team_id`, `requester_id`  | `""` removes the value.                                                                                                                          |
| `PATCH /accounts/{id}`                              | `channels`                                | Replaces the linked channels. Channels you leave out are unlinked from the account.                                                              |
|                                                     | `domains`, `primary_domain`               | Replaces the domains. `primary_domain` must be in `domains`.                                                                                     |
|                                                     | `tags`                                    | Replaces the list by default. Set `tags_apply_mode` to `append_only` or `remove_only` to only add or only remove the tags you send.              |
|                                                     | `external_ids`                            | Replaces the list.                                                                                                                               |
|                                                     | `subaccount_ids`                          | Replaces the subaccounts. Accounts you leave out stop being subaccounts.                                                                         |
|                                                     | `owner_id`                                | `""` removes the owner.                                                                                                                          |
| `PATCH /accounts` (bulk)                            | `tags`                                    | Set `tags_apply_mode` to `replace` (default), `append_only`, or `remove_only`.                                                                   |
| `PATCH /contacts/{id}`                              | `email`                                   | Replaces all of the contact's emails with this one.                                                                                              |
|                                                     | `emails`, `phone_numbers`, `external_ids` | Replaces the list.                                                                                                                               |
|                                                     | `account_id`                              | `""` removes the contact from its account.                                                                                                       |
| `PATCH /teams/{id}`                                 | `user_ids`                                | Replaces the team's members.                                                                                                                     |
| `PATCH /knowledge-bases/{id}/articles/{article_id}` | `tag_ids`                                 | Replaces the article's tags by default. Set `tags_apply_mode` to `append_only` or `remove_only` to only add or only remove the tags you send.    |

### Updating knowledge base articles

* `body_html` saves a new **draft**. The published article doesn't change until you publish.
* To publish the new body in the same request, also send `"publish_updated_body_html": true` or `"is_published": true`.
* `"is_published": false` unpublishes the article.
* `title`, `is_unlisted`, `visibility_config`, `collection_id`, and `author_user_id` apply to the live article right away.
* To update a translation, add `language`. The same draft and publish rules apply.

## Files and attachments

### Upload a file

[`POST /attachments`](https://docs.usepylon.com/pylon-docs/developer/api/api-reference/attachments.md) takes `multipart/form-data` with these fields:

| Field         | Required                    | Description                               |
| ------------- | --------------------------- | ----------------------------------------- |
| `file`        | One of `file` or `file_url` | The file to upload. One file per request. |
| `file_url`    | One of `file` or `file_url` | A URL Pylon downloads the file from.      |
| `description` | No                          | A description of the file.                |

```bash
curl https://api.usepylon.com/attachments \
  -H "Authorization: Bearer $PYLON_API_TOKEN" \
  -F "file=@screenshot.png" \
  -F "description=Error screenshot"
```

The response's `data` has the file's `id`, `name`, `url`, and `description`. Pass `url` in `attachment_urls` when you create an issue, reply, or internal note.

* Files up to 100 MB are supported. Larger files can be rejected with `413`; share those as a link instead. Email and chat channels may have smaller limits.
* Executables and script files are rejected with `400`.
* `attachment_urls` also accepts any publicly reachable URL. Pylon downloads the file and stores its own copy.

### Download a file

An issue's `attachment_urls` lists the files on its messages. Each message from [`GET /issues/{id}/messages`](https://docs.usepylon.com/pylon-docs/developer/api/api-reference/messages.md) has its files in `file_urls`.

* Most of these are signed links. Download them with a plain `GET`, without an `Authorization` header.
* They don't expire, so you can store them. Anyone with a link can download the file, so treat links as sensitive.
* Use the URL exactly as returned. Changing it invalidates the signature.
* Some older attachments return the URL they were originally stored with.

## Find slugs

The API refers to custom fields, select options, and statuses by slug, not by label.

| Slug          | In Pylon                                                                                                                             | Through the API                                                                                                                            |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| Custom field  | The **API Slug** column on field settings pages, such as **Settings > Issue data > Fields** and **Settings > Account data > Fields** | [`GET /custom-fields?object_type=issue`](https://docs.usepylon.com/pylon-docs/developer/api/api-reference/custom-fields.md) returns `slug` |
| Select option | **View and edit slugs** in the field's **…** menu                                                                                    | `select_metadata.options[].slug` in the same response                                                                                      |
| Issue status  | —                                                                                                                                    | [`GET /issue-statuses`](https://docs.usepylon.com/pylon-docs/developer/api/api-reference/issues.md) returns `slug`                         |
| User status   | —                                                                                                                                    | [`GET /user-statuses`](https://docs.usepylon.com/pylon-docs/developer/api/api-reference/users.md) returns `slug`                           |

`object_type` can be `account`, `issue`, `contact`, `task`, `project`, `meeting`, or `opportunity`. If you change a slug, update every integration that uses the old one.

Some slugs are reserved because they match built-in field names, for example account `state`, `source`, and `account_id`, and issue `subject`. If you send a reserved slug in `slug` when creating a custom field, the request is rejected. If you leave `slug` out and the field's label would produce a reserved slug, Pylon adds a number, for example `state_1`.


---

# 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.usepylon.com/pylon-docs/developer/api/conventions.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.
