> 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/api-reference/tasks-and-projects.md). # Tasks & Projects ## Get all tasks > Returns a paginated list of tasks for the organization.\ > \ > \*\*Rate limit:\*\* 300 requests per minute ```json {"openapi":"3.0.3","info":{"title":"Pylon API.","version":"1.0.0"},"tags":[],"servers":[{"description":"US region","url":"https://api.usepylon.com"},{"description":"EU region","url":"https://api.eu.usepylon.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"description":"Authorization: Bearer ","scheme":"bearer","type":"http"}},"responses":{"GetTasksResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetTasksResponseBody"}}},"description":""},"BadRequestApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request was invalid or could not be completed."},"UnauthorizedApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request could not be authenticated for this API."},"ForbiddenApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The authenticated caller or organization is not allowed to access this endpoint or operation."},"TooManyRequestsApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request exceeded the applicable rate limit.","headers":{"Retry-After":{"description":"Seconds until the next request to this endpoint is permitted.","schema":{"format":"int64","type":"integer"}},"X-Retry-After":{"description":"Seconds until the full per-minute allowance is restored. Capacity returns gradually before then.","schema":{"format":"int64","type":"integer"}}}},"InternalServerErrorApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"An unexpected internal error occurred."}},"schemas":{"GetTasksResponseBody":{"properties":{"data":{"description":"The data payload of the response.","items":{"$ref":"#/components/schemas/Task"},"type":"array"},"pagination":{"$ref":"#/components/schemas/Pagination"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"required":["data","request_id"],"type":"object"},"Task":{"properties":{"account":{"$ref":"#/components/schemas/MiniAccount"},"assignee":{"$ref":"#/components/schemas/Actor"},"body_html":{"description":"The body of the task in HTML format.","type":"string"},"completed_at":{"description":"The completion time of the task in RFC3339 format.","format":"date-time","type":"string"},"created_at":{"description":"The created at time of the task.","format":"date-time","type":"string"},"custom_fields":{"additionalProperties":{"$ref":"#/components/schemas/CustomFieldValue"},"description":"Custom field values associated with the task, keyed by custom field slug.","nullable":true,"type":"object"},"customer_portal_visible":{"description":"The customer portal visible of the task.","type":"boolean"},"due_date":{"description":"The due date of the task in RFC3339 format.","format":"date-time","type":"string"},"external_issues":{"description":"The external product issues associated with the task, if any.","items":{"$ref":"#/components/schemas/ExternalIssue"},"type":"array"},"id":{"description":"The ID of the task.","type":"string"},"linked_issues":{"description":"The Pylon issues linked to the task that the current user can access, if any.","items":{"$ref":"#/components/schemas/MiniIssue"},"type":"array"},"milestone":{"$ref":"#/components/schemas/MiniMilestone"},"parent_task_id":{"description":"The ID of the parent task, if this is a subtask.","type":"string"},"project":{"$ref":"#/components/schemas/MiniProject"},"status":{"$ref":"#/components/schemas/TaskStatus"},"subtask_ids":{"description":"The IDs of subtasks belonging to this task.","items":{"type":"string"},"nullable":true,"type":"array"},"title":{"description":"The title of the task.","type":"string"},"updated_at":{"description":"The updated at time of the task.","format":"date-time","type":"string"}},"required":["body_html","created_at","customer_portal_visible","id","status","title","updated_at"],"type":"object"},"MiniAccount":{"properties":{"external_ids":{"description":"External IDs associated with the account.","items":{"$ref":"#/components/schemas/ExternalID"},"nullable":true,"type":"array"},"id":{"description":"The ID of the account.","type":"string"}},"required":["id"],"type":"object"},"ExternalID":{"properties":{"external_id":{"description":"The external ID. Must be unique per object type (ex. account).","type":"string"},"label":{"description":"The label of the external ID. Must be unique per object.","type":"string"}},"type":"object"},"Actor":{"properties":{"contact":{"$ref":"#/components/schemas/MiniContact"},"user":{"$ref":"#/components/schemas/MiniUser"}},"type":"object"},"MiniContact":{"properties":{"email":{"description":"The email of the contact.","type":"string"},"id":{"description":"The ID of the contact.","type":"string"}},"required":["id"],"type":"object"},"MiniUser":{"properties":{"email":{"description":"The email of the user.","type":"string"},"id":{"description":"The ID of the user.","type":"string"}},"required":["id"],"type":"object"},"CustomFieldValue":{"description":"A custom field value to set. Custom fields not listed in a write request are left unchanged.","properties":{"slug":{"description":"The slug of the custom field.","type":"string"},"value":{"description":"The value of the custom field. Only to be used for single-valued custom fields. If unset, the custom field will be unset. If the custom field is a select field, the value must be the select option slug, which you can find from the GET /custom-fields endpoint. If the custom field is a relationship field, the value must be the related object ID.","type":"string"},"values":{"description":"The values of the custom field. Only to be used for multi-valued custom fields (ex. multiselect). Replaces the full selection; it does not add to or remove from the existing values. If unset, the custom field will be unset. If the custom field is a multiselect field, the values must be the select option slugs which you can find from the GET /custom-fields endpoint.","items":{"type":"string"},"type":"array"}},"title":"CustomFieldValue","type":"object"},"ExternalIssue":{"properties":{"external_id":{"description":"The external ID of the external issue.\nJira: ID of the issue (autoincrementing number from 10000).\nGitHub: Owner/Repo/IssueID.\nLinear: ID of the issue (UUID).\nAsana: ID of the task (Long number).","type":"string"},"link":{"description":"Link to the product issue.","type":"string"},"source":{"description":"The source of the external issue.","type":"string"}},"required":["external_id","link","source"],"type":"object"},"MiniIssue":{"properties":{"id":{"description":"The ID of the issue.","type":"string"},"number":{"description":"The number of the issue.","format":"int64","type":"integer"},"title":{"description":"The title of the issue.","type":"string"}},"required":["id","number","title"],"type":"object"},"MiniMilestone":{"properties":{"id":{"description":"The ID of the milestone.","type":"string"}},"required":["id"],"type":"object"},"MiniProject":{"properties":{"id":{"description":"The ID of the project.","type":"string"}},"required":["id"],"type":"object"},"TaskStatus":{"type":"string"},"Pagination":{"description":"Pagination information for list responses. Absent when there are no more results.","properties":{"cursor":{"description":"The cursor for the next page of results.","type":"string"},"has_next_page":{"description":"Indicates if there is a next page of results.","type":"boolean"}},"required":["cursor","has_next_page"],"title":"Pagination","type":"object"},"ErrorApiResponseBody":{"properties":{"code":{"description":"A stable machine-readable identifier for this failure, safe to branch on\ninstead of the message text. Omitted when the failure has no assigned code.\n\nKnown values: `recipients_suppressed`, `email_bounced`, `internal_issue_reply_not_allowed`, `duplicate_object`, `invalid_authorization_header`, `invalid_api_token`, `invalid_oauth_token`, `wrong_region_token`, `organization_deactivated`, `organization_suspended`, `permission_denied`, `oauth_not_permitted`, `rate_limited`, `not_found`, `method_not_allowed`, `payload_too_large`, `invalid_request_body`, `internal_error`, `invalid_webhook_credentials`, `organization_inactive`. This list is not exhaustive.","type":"string"},"errors":{"description":"The list of errors.","items":{"type":"string"},"type":"array"},"exists_id":{"description":"The ID of the object that already exists if this is a duplicate object error.","type":"string"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"required":["request_id"],"type":"object"}}},"paths":{"/tasks":{"get":{"description":"Returns a paginated list of tasks for the organization.\n\n**Rate limit:** 300 requests per minute","operationId":"GetTasks","parameters":[{"description":"The cursor to use for pagination.","in":"query","name":"cursor","schema":{"type":"string"}},{"description":"The number of tasks to fetch. Defaults to 100. Must be greater than 0 and less than 1000.","in":"query","name":"limit","schema":{"format":"int64","type":"integer"}}],"responses":{"200":{"$ref":"#/components/responses/GetTasksResponse"},"400":{"$ref":"#/components/responses/BadRequestApiResponse"},"401":{"$ref":"#/components/responses/UnauthorizedApiResponse"},"403":{"$ref":"#/components/responses/ForbiddenApiResponse"},"429":{"$ref":"#/components/responses/TooManyRequestsApiResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorApiResponse"}},"summary":"Get all tasks","tags":["tasks"]}}}} ``` ## Get a task by its ID > Returns a single task by ID.\ > \ > \*\*Rate limit:\*\* 300 requests per minute ```json {"openapi":"3.0.3","info":{"title":"Pylon API.","version":"1.0.0"},"tags":[],"servers":[{"description":"US region","url":"https://api.usepylon.com"},{"description":"EU region","url":"https://api.eu.usepylon.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"description":"Authorization: Bearer ","scheme":"bearer","type":"http"}},"responses":{"GetTaskResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetTaskResponseBody"}}},"description":""},"BadRequestApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request was invalid or could not be completed."},"UnauthorizedApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request could not be authenticated for this API."},"ForbiddenApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The authenticated caller or organization is not allowed to access this endpoint or operation."},"ErrorApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":""},"TooManyRequestsApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request exceeded the applicable rate limit.","headers":{"Retry-After":{"description":"Seconds until the next request to this endpoint is permitted.","schema":{"format":"int64","type":"integer"}},"X-Retry-After":{"description":"Seconds until the full per-minute allowance is restored. Capacity returns gradually before then.","schema":{"format":"int64","type":"integer"}}}},"InternalServerErrorApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"An unexpected internal error occurred."}},"schemas":{"GetTaskResponseBody":{"properties":{"data":{"$ref":"#/components/schemas/Task"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"required":["data","request_id"],"type":"object"},"Task":{"properties":{"account":{"$ref":"#/components/schemas/MiniAccount"},"assignee":{"$ref":"#/components/schemas/Actor"},"body_html":{"description":"The body of the task in HTML format.","type":"string"},"completed_at":{"description":"The completion time of the task in RFC3339 format.","format":"date-time","type":"string"},"created_at":{"description":"The created at time of the task.","format":"date-time","type":"string"},"custom_fields":{"additionalProperties":{"$ref":"#/components/schemas/CustomFieldValue"},"description":"Custom field values associated with the task, keyed by custom field slug.","nullable":true,"type":"object"},"customer_portal_visible":{"description":"The customer portal visible of the task.","type":"boolean"},"due_date":{"description":"The due date of the task in RFC3339 format.","format":"date-time","type":"string"},"external_issues":{"description":"The external product issues associated with the task, if any.","items":{"$ref":"#/components/schemas/ExternalIssue"},"type":"array"},"id":{"description":"The ID of the task.","type":"string"},"linked_issues":{"description":"The Pylon issues linked to the task that the current user can access, if any.","items":{"$ref":"#/components/schemas/MiniIssue"},"type":"array"},"milestone":{"$ref":"#/components/schemas/MiniMilestone"},"parent_task_id":{"description":"The ID of the parent task, if this is a subtask.","type":"string"},"project":{"$ref":"#/components/schemas/MiniProject"},"status":{"$ref":"#/components/schemas/TaskStatus"},"subtask_ids":{"description":"The IDs of subtasks belonging to this task.","items":{"type":"string"},"nullable":true,"type":"array"},"title":{"description":"The title of the task.","type":"string"},"updated_at":{"description":"The updated at time of the task.","format":"date-time","type":"string"}},"required":["body_html","created_at","customer_portal_visible","id","status","title","updated_at"],"type":"object"},"MiniAccount":{"properties":{"external_ids":{"description":"External IDs associated with the account.","items":{"$ref":"#/components/schemas/ExternalID"},"nullable":true,"type":"array"},"id":{"description":"The ID of the account.","type":"string"}},"required":["id"],"type":"object"},"ExternalID":{"properties":{"external_id":{"description":"The external ID. Must be unique per object type (ex. account).","type":"string"},"label":{"description":"The label of the external ID. Must be unique per object.","type":"string"}},"type":"object"},"Actor":{"properties":{"contact":{"$ref":"#/components/schemas/MiniContact"},"user":{"$ref":"#/components/schemas/MiniUser"}},"type":"object"},"MiniContact":{"properties":{"email":{"description":"The email of the contact.","type":"string"},"id":{"description":"The ID of the contact.","type":"string"}},"required":["id"],"type":"object"},"MiniUser":{"properties":{"email":{"description":"The email of the user.","type":"string"},"id":{"description":"The ID of the user.","type":"string"}},"required":["id"],"type":"object"},"CustomFieldValue":{"description":"A custom field value to set. Custom fields not listed in a write request are left unchanged.","properties":{"slug":{"description":"The slug of the custom field.","type":"string"},"value":{"description":"The value of the custom field. Only to be used for single-valued custom fields. If unset, the custom field will be unset. If the custom field is a select field, the value must be the select option slug, which you can find from the GET /custom-fields endpoint. If the custom field is a relationship field, the value must be the related object ID.","type":"string"},"values":{"description":"The values of the custom field. Only to be used for multi-valued custom fields (ex. multiselect). Replaces the full selection; it does not add to or remove from the existing values. If unset, the custom field will be unset. If the custom field is a multiselect field, the values must be the select option slugs which you can find from the GET /custom-fields endpoint.","items":{"type":"string"},"type":"array"}},"title":"CustomFieldValue","type":"object"},"ExternalIssue":{"properties":{"external_id":{"description":"The external ID of the external issue.\nJira: ID of the issue (autoincrementing number from 10000).\nGitHub: Owner/Repo/IssueID.\nLinear: ID of the issue (UUID).\nAsana: ID of the task (Long number).","type":"string"},"link":{"description":"Link to the product issue.","type":"string"},"source":{"description":"The source of the external issue.","type":"string"}},"required":["external_id","link","source"],"type":"object"},"MiniIssue":{"properties":{"id":{"description":"The ID of the issue.","type":"string"},"number":{"description":"The number of the issue.","format":"int64","type":"integer"},"title":{"description":"The title of the issue.","type":"string"}},"required":["id","number","title"],"type":"object"},"MiniMilestone":{"properties":{"id":{"description":"The ID of the milestone.","type":"string"}},"required":["id"],"type":"object"},"MiniProject":{"properties":{"id":{"description":"The ID of the project.","type":"string"}},"required":["id"],"type":"object"},"TaskStatus":{"type":"string"},"ErrorApiResponseBody":{"properties":{"code":{"description":"A stable machine-readable identifier for this failure, safe to branch on\ninstead of the message text. Omitted when the failure has no assigned code.\n\nKnown values: `recipients_suppressed`, `email_bounced`, `internal_issue_reply_not_allowed`, `duplicate_object`, `invalid_authorization_header`, `invalid_api_token`, `invalid_oauth_token`, `wrong_region_token`, `organization_deactivated`, `organization_suspended`, `permission_denied`, `oauth_not_permitted`, `rate_limited`, `not_found`, `method_not_allowed`, `payload_too_large`, `invalid_request_body`, `internal_error`, `invalid_webhook_credentials`, `organization_inactive`. This list is not exhaustive.","type":"string"},"errors":{"description":"The list of errors.","items":{"type":"string"},"type":"array"},"exists_id":{"description":"The ID of the object that already exists if this is a duplicate object error.","type":"string"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"required":["request_id"],"type":"object"}}},"paths":{"/tasks/{id}":{"get":{"description":"Returns a single task by ID.\n\n**Rate limit:** 300 requests per minute","operationId":"GetTask","parameters":[{"description":"The ID of the task to fetch.","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/GetTaskResponse"},"400":{"$ref":"#/components/responses/BadRequestApiResponse"},"401":{"$ref":"#/components/responses/UnauthorizedApiResponse"},"403":{"$ref":"#/components/responses/ForbiddenApiResponse"},"404":{"$ref":"#/components/responses/ErrorApiResponse"},"429":{"$ref":"#/components/responses/TooManyRequestsApiResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorApiResponse"}},"summary":"Get a task by its ID","tags":["tasks"]}}}} ``` ## Get comments for a task > Returns all comments for a task, ordered by creation time.\ > \ > \*\*Rate limit:\*\* 300 requests per minute ```json {"openapi":"3.0.3","info":{"title":"Pylon API.","version":"1.0.0"},"tags":[],"servers":[{"description":"US region","url":"https://api.usepylon.com"},{"description":"EU region","url":"https://api.eu.usepylon.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"description":"Authorization: Bearer ","scheme":"bearer","type":"http"}},"responses":{"GetTaskCommentsResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetTaskCommentsResponseBody"}}},"description":""},"BadRequestApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request was invalid or could not be completed."},"UnauthorizedApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request could not be authenticated for this API."},"ForbiddenApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The authenticated caller or organization is not allowed to access this endpoint or operation."},"ErrorApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":""},"TooManyRequestsApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request exceeded the applicable rate limit.","headers":{"Retry-After":{"description":"Seconds until the next request to this endpoint is permitted.","schema":{"format":"int64","type":"integer"}},"X-Retry-After":{"description":"Seconds until the full per-minute allowance is restored. Capacity returns gradually before then.","schema":{"format":"int64","type":"integer"}}}},"InternalServerErrorApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"An unexpected internal error occurred."}},"schemas":{"GetTaskCommentsResponseBody":{"properties":{"data":{"description":"The data payload of the response.","items":{"$ref":"#/components/schemas/TaskComment"},"type":"array"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"required":["data","request_id"],"type":"object"},"TaskComment":{"properties":{"author":{"$ref":"#/components/schemas/Actor"},"body_html":{"description":"The body of the comment in HTML format.","type":"string"},"created_at":{"description":"The created at time of the comment.","format":"date-time","type":"string"},"id":{"description":"The ID of the comment.","type":"string"},"is_internal":{"description":"Whether the comment is visible only to internal users.","type":"boolean"},"last_edited_at":{"description":"The time the comment was last edited, in RFC3339 format.","format":"date-time","type":"string"},"task_id":{"description":"The ID of the task this comment belongs to.","type":"string"},"updated_at":{"description":"The updated at time of the comment.","format":"date-time","type":"string"}},"required":["body_html","created_at","id","is_internal","task_id","updated_at"],"type":"object"},"Actor":{"properties":{"contact":{"$ref":"#/components/schemas/MiniContact"},"user":{"$ref":"#/components/schemas/MiniUser"}},"type":"object"},"MiniContact":{"properties":{"email":{"description":"The email of the contact.","type":"string"},"id":{"description":"The ID of the contact.","type":"string"}},"required":["id"],"type":"object"},"MiniUser":{"properties":{"email":{"description":"The email of the user.","type":"string"},"id":{"description":"The ID of the user.","type":"string"}},"required":["id"],"type":"object"},"ErrorApiResponseBody":{"properties":{"code":{"description":"A stable machine-readable identifier for this failure, safe to branch on\ninstead of the message text. Omitted when the failure has no assigned code.\n\nKnown values: `recipients_suppressed`, `email_bounced`, `internal_issue_reply_not_allowed`, `duplicate_object`, `invalid_authorization_header`, `invalid_api_token`, `invalid_oauth_token`, `wrong_region_token`, `organization_deactivated`, `organization_suspended`, `permission_denied`, `oauth_not_permitted`, `rate_limited`, `not_found`, `method_not_allowed`, `payload_too_large`, `invalid_request_body`, `internal_error`, `invalid_webhook_credentials`, `organization_inactive`. This list is not exhaustive.","type":"string"},"errors":{"description":"The list of errors.","items":{"type":"string"},"type":"array"},"exists_id":{"description":"The ID of the object that already exists if this is a duplicate object error.","type":"string"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"required":["request_id"],"type":"object"}}},"paths":{"/tasks/{id}/comments":{"get":{"description":"Returns all comments for a task, ordered by creation time.\n\n**Rate limit:** 300 requests per minute","operationId":"GetTaskComments","parameters":[{"description":"The ID of the task to fetch comments for.","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/GetTaskCommentsResponse"},"400":{"$ref":"#/components/responses/BadRequestApiResponse"},"401":{"$ref":"#/components/responses/UnauthorizedApiResponse"},"403":{"$ref":"#/components/responses/ForbiddenApiResponse"},"404":{"$ref":"#/components/responses/ErrorApiResponse"},"429":{"$ref":"#/components/responses/TooManyRequestsApiResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorApiResponse"}},"summary":"Get comments for a task","tags":["tasks"]}}}} ``` ## Create a comment on a task > Creates a new comment on a task. The authenticated user is the author.\ > \ > \*\*Rate limit:\*\* 120 requests per minute ```json {"openapi":"3.0.3","info":{"title":"Pylon API.","version":"1.0.0"},"tags":[],"servers":[{"description":"US region","url":"https://api.usepylon.com"},{"description":"EU region","url":"https://api.eu.usepylon.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"description":"Authorization: Bearer ","scheme":"bearer","type":"http"}},"schemas":{"CreateTaskCommentRequestBody":{"properties":{"body_html":{"description":"The body of the comment in HTML format.","type":"string"},"is_internal":{"description":"Whether the comment is visible only to internal users.","type":"boolean"}},"required":["body_html"],"type":"object"},"CreateTaskCommentResponseBody":{"properties":{"data":{"$ref":"#/components/schemas/TaskComment"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"required":["data","request_id"],"type":"object"},"TaskComment":{"properties":{"author":{"$ref":"#/components/schemas/Actor"},"body_html":{"description":"The body of the comment in HTML format.","type":"string"},"created_at":{"description":"The created at time of the comment.","format":"date-time","type":"string"},"id":{"description":"The ID of the comment.","type":"string"},"is_internal":{"description":"Whether the comment is visible only to internal users.","type":"boolean"},"last_edited_at":{"description":"The time the comment was last edited, in RFC3339 format.","format":"date-time","type":"string"},"task_id":{"description":"The ID of the task this comment belongs to.","type":"string"},"updated_at":{"description":"The updated at time of the comment.","format":"date-time","type":"string"}},"required":["body_html","created_at","id","is_internal","task_id","updated_at"],"type":"object"},"Actor":{"properties":{"contact":{"$ref":"#/components/schemas/MiniContact"},"user":{"$ref":"#/components/schemas/MiniUser"}},"type":"object"},"MiniContact":{"properties":{"email":{"description":"The email of the contact.","type":"string"},"id":{"description":"The ID of the contact.","type":"string"}},"required":["id"],"type":"object"},"MiniUser":{"properties":{"email":{"description":"The email of the user.","type":"string"},"id":{"description":"The ID of the user.","type":"string"}},"required":["id"],"type":"object"},"ErrorApiResponseBody":{"properties":{"code":{"description":"A stable machine-readable identifier for this failure, safe to branch on\ninstead of the message text. Omitted when the failure has no assigned code.\n\nKnown values: `recipients_suppressed`, `email_bounced`, `internal_issue_reply_not_allowed`, `duplicate_object`, `invalid_authorization_header`, `invalid_api_token`, `invalid_oauth_token`, `wrong_region_token`, `organization_deactivated`, `organization_suspended`, `permission_denied`, `oauth_not_permitted`, `rate_limited`, `not_found`, `method_not_allowed`, `payload_too_large`, `invalid_request_body`, `internal_error`, `invalid_webhook_credentials`, `organization_inactive`. This list is not exhaustive.","type":"string"},"errors":{"description":"The list of errors.","items":{"type":"string"},"type":"array"},"exists_id":{"description":"The ID of the object that already exists if this is a duplicate object error.","type":"string"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"required":["request_id"],"type":"object"}},"responses":{"CreateTaskCommentResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTaskCommentResponseBody"}}},"description":""},"BadRequestApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request was invalid or could not be completed."},"UnauthorizedApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request could not be authenticated for this API."},"ForbiddenApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The authenticated caller or organization is not allowed to access this endpoint or operation."},"ErrorApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":""},"TooManyRequestsApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request exceeded the applicable rate limit.","headers":{"Retry-After":{"description":"Seconds until the next request to this endpoint is permitted.","schema":{"format":"int64","type":"integer"}},"X-Retry-After":{"description":"Seconds until the full per-minute allowance is restored. Capacity returns gradually before then.","schema":{"format":"int64","type":"integer"}}}},"InternalServerErrorApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"An unexpected internal error occurred."}}},"paths":{"/tasks/{id}/comments":{"post":{"description":"Creates a new comment on a task. The authenticated user is the author.\n\n**Rate limit:** 120 requests per minute","operationId":"CreateTaskComment","parameters":[{"description":"The ID of the task to add a comment to.","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTaskCommentRequestBody"}}}},"responses":{"200":{"$ref":"#/components/responses/CreateTaskCommentResponse"},"400":{"$ref":"#/components/responses/BadRequestApiResponse"},"401":{"$ref":"#/components/responses/UnauthorizedApiResponse"},"403":{"$ref":"#/components/responses/ForbiddenApiResponse"},"404":{"$ref":"#/components/responses/ErrorApiResponse"},"429":{"$ref":"#/components/responses/TooManyRequestsApiResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorApiResponse"}},"summary":"Create a comment on a task","tags":["tasks"]}}}} ``` ## Update a comment on a task > Updates an existing comment. Only the original author can update their comment.\ > \ > \*\*Rate limit:\*\* 120 requests per minute ```json {"openapi":"3.0.3","info":{"title":"Pylon API.","version":"1.0.0"},"tags":[],"servers":[{"description":"US region","url":"https://api.usepylon.com"},{"description":"EU region","url":"https://api.eu.usepylon.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"description":"Authorization: Bearer ","scheme":"bearer","type":"http"}},"schemas":{"UpdateTaskCommentRequestBody":{"properties":{"body_html":{"description":"The updated body of the comment in HTML format.","type":"string"}},"required":["body_html"],"type":"object"},"UpdateTaskCommentResponseBody":{"properties":{"data":{"$ref":"#/components/schemas/TaskComment"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"required":["data","request_id"],"type":"object"},"TaskComment":{"properties":{"author":{"$ref":"#/components/schemas/Actor"},"body_html":{"description":"The body of the comment in HTML format.","type":"string"},"created_at":{"description":"The created at time of the comment.","format":"date-time","type":"string"},"id":{"description":"The ID of the comment.","type":"string"},"is_internal":{"description":"Whether the comment is visible only to internal users.","type":"boolean"},"last_edited_at":{"description":"The time the comment was last edited, in RFC3339 format.","format":"date-time","type":"string"},"task_id":{"description":"The ID of the task this comment belongs to.","type":"string"},"updated_at":{"description":"The updated at time of the comment.","format":"date-time","type":"string"}},"required":["body_html","created_at","id","is_internal","task_id","updated_at"],"type":"object"},"Actor":{"properties":{"contact":{"$ref":"#/components/schemas/MiniContact"},"user":{"$ref":"#/components/schemas/MiniUser"}},"type":"object"},"MiniContact":{"properties":{"email":{"description":"The email of the contact.","type":"string"},"id":{"description":"The ID of the contact.","type":"string"}},"required":["id"],"type":"object"},"MiniUser":{"properties":{"email":{"description":"The email of the user.","type":"string"},"id":{"description":"The ID of the user.","type":"string"}},"required":["id"],"type":"object"},"ErrorApiResponseBody":{"properties":{"code":{"description":"A stable machine-readable identifier for this failure, safe to branch on\ninstead of the message text. Omitted when the failure has no assigned code.\n\nKnown values: `recipients_suppressed`, `email_bounced`, `internal_issue_reply_not_allowed`, `duplicate_object`, `invalid_authorization_header`, `invalid_api_token`, `invalid_oauth_token`, `wrong_region_token`, `organization_deactivated`, `organization_suspended`, `permission_denied`, `oauth_not_permitted`, `rate_limited`, `not_found`, `method_not_allowed`, `payload_too_large`, `invalid_request_body`, `internal_error`, `invalid_webhook_credentials`, `organization_inactive`. This list is not exhaustive.","type":"string"},"errors":{"description":"The list of errors.","items":{"type":"string"},"type":"array"},"exists_id":{"description":"The ID of the object that already exists if this is a duplicate object error.","type":"string"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"required":["request_id"],"type":"object"}},"responses":{"UpdateTaskCommentResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateTaskCommentResponseBody"}}},"description":""},"BadRequestApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request was invalid or could not be completed."},"UnauthorizedApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request could not be authenticated for this API."},"ForbiddenApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The authenticated caller or organization is not allowed to access this endpoint or operation."},"ErrorApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":""},"TooManyRequestsApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request exceeded the applicable rate limit.","headers":{"Retry-After":{"description":"Seconds until the next request to this endpoint is permitted.","schema":{"format":"int64","type":"integer"}},"X-Retry-After":{"description":"Seconds until the full per-minute allowance is restored. Capacity returns gradually before then.","schema":{"format":"int64","type":"integer"}}}},"InternalServerErrorApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"An unexpected internal error occurred."}}},"paths":{"/tasks/{id}/comments/{comment_id}":{"patch":{"description":"Updates an existing comment. Only the original author can update their comment.\n\n**Rate limit:** 120 requests per minute","operationId":"UpdateTaskComment","parameters":[{"description":"The ID of the task.","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"The ID of the comment to update.","in":"path","name":"comment_id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateTaskCommentRequestBody"}}}},"responses":{"200":{"$ref":"#/components/responses/UpdateTaskCommentResponse"},"400":{"$ref":"#/components/responses/BadRequestApiResponse"},"401":{"$ref":"#/components/responses/UnauthorizedApiResponse"},"403":{"$ref":"#/components/responses/ForbiddenApiResponse"},"404":{"$ref":"#/components/responses/ErrorApiResponse"},"429":{"$ref":"#/components/responses/TooManyRequestsApiResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorApiResponse"}},"summary":"Update a comment on a task","tags":["tasks"]}}}} ``` ## Delete a comment on a task > Deletes an existing comment. Only the original author can delete their comment.\ > \ > \*\*Rate limit:\*\* 120 requests per minute ```json {"openapi":"3.0.3","info":{"title":"Pylon API.","version":"1.0.0"},"tags":[],"servers":[{"description":"US region","url":"https://api.usepylon.com"},{"description":"EU region","url":"https://api.eu.usepylon.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"description":"Authorization: Bearer ","scheme":"bearer","type":"http"}},"responses":{"DeleteTaskCommentResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteTaskCommentResponseBody"}}},"description":""},"BadRequestApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request was invalid or could not be completed."},"UnauthorizedApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request could not be authenticated for this API."},"ForbiddenApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The authenticated caller or organization is not allowed to access this endpoint or operation."},"ErrorApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":""},"TooManyRequestsApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request exceeded the applicable rate limit.","headers":{"Retry-After":{"description":"Seconds until the next request to this endpoint is permitted.","schema":{"format":"int64","type":"integer"}},"X-Retry-After":{"description":"Seconds until the full per-minute allowance is restored. Capacity returns gradually before then.","schema":{"format":"int64","type":"integer"}}}},"InternalServerErrorApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"An unexpected internal error occurred."}},"schemas":{"DeleteTaskCommentResponseBody":{"properties":{"request_id":{"description":"The request ID for tracking.","type":"string"}},"required":["request_id"],"type":"object"},"ErrorApiResponseBody":{"properties":{"code":{"description":"A stable machine-readable identifier for this failure, safe to branch on\ninstead of the message text. Omitted when the failure has no assigned code.\n\nKnown values: `recipients_suppressed`, `email_bounced`, `internal_issue_reply_not_allowed`, `duplicate_object`, `invalid_authorization_header`, `invalid_api_token`, `invalid_oauth_token`, `wrong_region_token`, `organization_deactivated`, `organization_suspended`, `permission_denied`, `oauth_not_permitted`, `rate_limited`, `not_found`, `method_not_allowed`, `payload_too_large`, `invalid_request_body`, `internal_error`, `invalid_webhook_credentials`, `organization_inactive`. This list is not exhaustive.","type":"string"},"errors":{"description":"The list of errors.","items":{"type":"string"},"type":"array"},"exists_id":{"description":"The ID of the object that already exists if this is a duplicate object error.","type":"string"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"required":["request_id"],"type":"object"}}},"paths":{"/tasks/{id}/comments/{comment_id}":{"delete":{"description":"Deletes an existing comment. Only the original author can delete their comment.\n\n**Rate limit:** 120 requests per minute","operationId":"DeleteTaskComment","parameters":[{"description":"The ID of the task.","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"The ID of the comment to delete.","in":"path","name":"comment_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/DeleteTaskCommentResponse"},"400":{"$ref":"#/components/responses/BadRequestApiResponse"},"401":{"$ref":"#/components/responses/UnauthorizedApiResponse"},"403":{"$ref":"#/components/responses/ForbiddenApiResponse"},"404":{"$ref":"#/components/responses/ErrorApiResponse"},"429":{"$ref":"#/components/responses/TooManyRequestsApiResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorApiResponse"}},"summary":"Delete a comment on a task","tags":["tasks"]}}}} ``` ## Search for tasks by a given filter > Filterable fields and their allowed operators:\ > \ > Field | Allowed operators |\ > \--- | --- |\ > \`account\_id\` | \`equals\`, \`in\`, \`not\_in\`, \`is\_set\` |\ > \`project\_id\` | \`equals\`, \`in\`, \`not\_in\`, \`is\_set\`, \`is\_unset\` |\ > \`status\` | \`equals\`, \`in\`, \`not\_in\` |\ > \`assignee\_id\` | \`equals\`, \`in\`, \`not\_in\`, \`is\_set\` |\ > \`milestone\_id\` | \`equals\`, \`in\`, \`not\_in\`, \`is\_set\` |\ > \`created\_at\` | \`time\_is\_after\`, \`time\_is\_before\`, \`time\_range\` |\ > \`due\_date\` | \`time\_is\_after\`, \`time\_is\_before\`, \`time\_range\`, \`is\_set\` |\ > \`updated\_at\` | \`time\_is\_after\`, \`time\_is\_before\`, \`time\_range\` |\ > \ > Timestamp values use RFC3339 format. Valid \`status\` values are \`not\_started\`, \`in\_progress\`, and \`completed\`. For custom fields, pass the field slug as \`field\`.\ > \ > \*\*Rate limit:\*\* 120 requests per minute ```json {"openapi":"3.0.3","info":{"title":"Pylon API.","version":"1.0.0"},"tags":[],"servers":[{"description":"US region","url":"https://api.usepylon.com"},{"description":"EU region","url":"https://api.eu.usepylon.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"description":"Authorization: Bearer ","scheme":"bearer","type":"http"}},"schemas":{"SearchTasksRequest":{"properties":{"cursor":{"description":"The cursor to use for pagination.","type":"string"},"filter":{"$ref":"#/components/schemas/Filter"},"limit":{"description":"The number of tasks to fetch. Defaults to 100. Must be between 1 and 1000.","format":"int64","type":"integer"}},"type":"object"},"Filter":{"properties":{"field":{"description":"The field for this filter. For allowed fields, see the documentation for\nthe specific endpoint you are using.\nFor non-compound filters (any operators other than \"and\" or \"or\"),\nfield must be set, along with either value or values, depending on the operator.","type":"string"},"operator":{"description":"The operator for this filter.","enum":["equals","not_equals","contains","does_not_contain","in","not_in","and","or","time_is_after","time_is_before","time_range","string_contains","string_does_not_contain","is_set","is_unset","greater_than","less_than","greater_than_or_equals","less_than_or_equals","includes_all_of","starts_with","ends_with"],"type":"string"},"subfilters":{"description":"Sub-filters for this filter. Valid only when operator is \"and\" or \"or\".\nThe maximum allowed depth for a tree of filters is 3, counting the top-level filter.","items":{"$ref":"#/components/schemas/Filter"},"type":"array"},"value":{"description":"The value for this filter. Used by single-valued operators: \"equals\", \"not_equals\",\n\"contains\", \"does_not_contain\", \"string_contains\", \"string_does_not_contain\",\n\"starts_with\", \"ends_with\", \"time_is_after\", \"time_is_before\", \"greater_than\",\n\"less_than\", \"greater_than_or_equals\", and \"less_than_or_equals\".","type":"string"},"values":{"description":"The values for this filter. Used by multi-valued operators: \"in\", \"not_in\", and\n\"includes_all_of\". For \"time_range\", set to [start, end].","items":{"type":"string"},"type":"array"}},"required":["operator"],"type":"object"},"SearchTasksResponseBody":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Task"},"type":"array"},"pagination":{"$ref":"#/components/schemas/Pagination"},"request_id":{"type":"string"}},"required":["data","request_id"],"type":"object"},"Task":{"properties":{"account":{"$ref":"#/components/schemas/MiniAccount"},"assignee":{"$ref":"#/components/schemas/Actor"},"body_html":{"description":"The body of the task in HTML format.","type":"string"},"completed_at":{"description":"The completion time of the task in RFC3339 format.","format":"date-time","type":"string"},"created_at":{"description":"The created at time of the task.","format":"date-time","type":"string"},"custom_fields":{"additionalProperties":{"$ref":"#/components/schemas/CustomFieldValue"},"description":"Custom field values associated with the task, keyed by custom field slug.","nullable":true,"type":"object"},"customer_portal_visible":{"description":"The customer portal visible of the task.","type":"boolean"},"due_date":{"description":"The due date of the task in RFC3339 format.","format":"date-time","type":"string"},"external_issues":{"description":"The external product issues associated with the task, if any.","items":{"$ref":"#/components/schemas/ExternalIssue"},"type":"array"},"id":{"description":"The ID of the task.","type":"string"},"linked_issues":{"description":"The Pylon issues linked to the task that the current user can access, if any.","items":{"$ref":"#/components/schemas/MiniIssue"},"type":"array"},"milestone":{"$ref":"#/components/schemas/MiniMilestone"},"parent_task_id":{"description":"The ID of the parent task, if this is a subtask.","type":"string"},"project":{"$ref":"#/components/schemas/MiniProject"},"status":{"$ref":"#/components/schemas/TaskStatus"},"subtask_ids":{"description":"The IDs of subtasks belonging to this task.","items":{"type":"string"},"nullable":true,"type":"array"},"title":{"description":"The title of the task.","type":"string"},"updated_at":{"description":"The updated at time of the task.","format":"date-time","type":"string"}},"required":["body_html","created_at","customer_portal_visible","id","status","title","updated_at"],"type":"object"},"MiniAccount":{"properties":{"external_ids":{"description":"External IDs associated with the account.","items":{"$ref":"#/components/schemas/ExternalID"},"nullable":true,"type":"array"},"id":{"description":"The ID of the account.","type":"string"}},"required":["id"],"type":"object"},"ExternalID":{"properties":{"external_id":{"description":"The external ID. Must be unique per object type (ex. account).","type":"string"},"label":{"description":"The label of the external ID. Must be unique per object.","type":"string"}},"type":"object"},"Actor":{"properties":{"contact":{"$ref":"#/components/schemas/MiniContact"},"user":{"$ref":"#/components/schemas/MiniUser"}},"type":"object"},"MiniContact":{"properties":{"email":{"description":"The email of the contact.","type":"string"},"id":{"description":"The ID of the contact.","type":"string"}},"required":["id"],"type":"object"},"MiniUser":{"properties":{"email":{"description":"The email of the user.","type":"string"},"id":{"description":"The ID of the user.","type":"string"}},"required":["id"],"type":"object"},"CustomFieldValue":{"description":"A custom field value to set. Custom fields not listed in a write request are left unchanged.","properties":{"slug":{"description":"The slug of the custom field.","type":"string"},"value":{"description":"The value of the custom field. Only to be used for single-valued custom fields. If unset, the custom field will be unset. If the custom field is a select field, the value must be the select option slug, which you can find from the GET /custom-fields endpoint. If the custom field is a relationship field, the value must be the related object ID.","type":"string"},"values":{"description":"The values of the custom field. Only to be used for multi-valued custom fields (ex. multiselect). Replaces the full selection; it does not add to or remove from the existing values. If unset, the custom field will be unset. If the custom field is a multiselect field, the values must be the select option slugs which you can find from the GET /custom-fields endpoint.","items":{"type":"string"},"type":"array"}},"title":"CustomFieldValue","type":"object"},"ExternalIssue":{"properties":{"external_id":{"description":"The external ID of the external issue.\nJira: ID of the issue (autoincrementing number from 10000).\nGitHub: Owner/Repo/IssueID.\nLinear: ID of the issue (UUID).\nAsana: ID of the task (Long number).","type":"string"},"link":{"description":"Link to the product issue.","type":"string"},"source":{"description":"The source of the external issue.","type":"string"}},"required":["external_id","link","source"],"type":"object"},"MiniIssue":{"properties":{"id":{"description":"The ID of the issue.","type":"string"},"number":{"description":"The number of the issue.","format":"int64","type":"integer"},"title":{"description":"The title of the issue.","type":"string"}},"required":["id","number","title"],"type":"object"},"MiniMilestone":{"properties":{"id":{"description":"The ID of the milestone.","type":"string"}},"required":["id"],"type":"object"},"MiniProject":{"properties":{"id":{"description":"The ID of the project.","type":"string"}},"required":["id"],"type":"object"},"TaskStatus":{"type":"string"},"Pagination":{"description":"Pagination information for list responses. Absent when there are no more results.","properties":{"cursor":{"description":"The cursor for the next page of results.","type":"string"},"has_next_page":{"description":"Indicates if there is a next page of results.","type":"boolean"}},"required":["cursor","has_next_page"],"title":"Pagination","type":"object"},"ErrorApiResponseBody":{"properties":{"code":{"description":"A stable machine-readable identifier for this failure, safe to branch on\ninstead of the message text. Omitted when the failure has no assigned code.\n\nKnown values: `recipients_suppressed`, `email_bounced`, `internal_issue_reply_not_allowed`, `duplicate_object`, `invalid_authorization_header`, `invalid_api_token`, `invalid_oauth_token`, `wrong_region_token`, `organization_deactivated`, `organization_suspended`, `permission_denied`, `oauth_not_permitted`, `rate_limited`, `not_found`, `method_not_allowed`, `payload_too_large`, `invalid_request_body`, `internal_error`, `invalid_webhook_credentials`, `organization_inactive`. This list is not exhaustive.","type":"string"},"errors":{"description":"The list of errors.","items":{"type":"string"},"type":"array"},"exists_id":{"description":"The ID of the object that already exists if this is a duplicate object error.","type":"string"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"required":["request_id"],"type":"object"}},"responses":{"SearchTasksResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchTasksResponseBody"}}},"description":""},"BadRequestApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request was invalid or could not be completed."},"UnauthorizedApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request could not be authenticated for this API."},"ForbiddenApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The authenticated caller or organization is not allowed to access this endpoint or operation."},"TooManyRequestsApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request exceeded the applicable rate limit.","headers":{"Retry-After":{"description":"Seconds until the next request to this endpoint is permitted.","schema":{"format":"int64","type":"integer"}},"X-Retry-After":{"description":"Seconds until the full per-minute allowance is restored. Capacity returns gradually before then.","schema":{"format":"int64","type":"integer"}}}},"InternalServerErrorApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"An unexpected internal error occurred."}}},"paths":{"/tasks/search":{"post":{"description":"Filterable fields and their allowed operators:\n\n Field | Allowed operators |\n --- | --- |\n `account_id` | `equals`, `in`, `not_in`, `is_set` |\n `project_id` | `equals`, `in`, `not_in`, `is_set`, `is_unset` |\n `status` | `equals`, `in`, `not_in` |\n `assignee_id` | `equals`, `in`, `not_in`, `is_set` |\n `milestone_id` | `equals`, `in`, `not_in`, `is_set` |\n `created_at` | `time_is_after`, `time_is_before`, `time_range` |\n `due_date` | `time_is_after`, `time_is_before`, `time_range`, `is_set` |\n `updated_at` | `time_is_after`, `time_is_before`, `time_range` |\n\nTimestamp values use RFC3339 format. Valid `status` values are `not_started`, `in_progress`, and `completed`. For custom fields, pass the field slug as `field`.\n\n**Rate limit:** 120 requests per minute","operationId":"SearchTasks","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchTasksRequest"}}}},"responses":{"200":{"$ref":"#/components/responses/SearchTasksResponse"},"400":{"$ref":"#/components/responses/BadRequestApiResponse"},"401":{"$ref":"#/components/responses/UnauthorizedApiResponse"},"403":{"$ref":"#/components/responses/ForbiddenApiResponse"},"429":{"$ref":"#/components/responses/TooManyRequestsApiResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorApiResponse"}},"summary":"Search for tasks by a given filter","tags":["tasks"]}}}} ``` ## Create a task > Creates a new task with a title and optional metadata.\ > \ > \*\*Rate limit:\*\* 300 requests per minute ```json {"openapi":"3.0.3","info":{"title":"Pylon API.","version":"1.0.0"},"tags":[],"servers":[{"description":"US region","url":"https://api.usepylon.com"},{"description":"EU region","url":"https://api.eu.usepylon.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"description":"Authorization: Bearer ","scheme":"bearer","type":"http"}},"schemas":{"CreateTaskRequestBody":{"properties":{"account_id":{"description":"Account ID for this task","type":"string"},"assignee_id":{"description":"Assignee ID for this task","type":"string"},"body_html":{"description":"Body HTML for this task","type":"string"},"custom_fields":{"description":"An array of custom fields to be used on this task.","items":{"$ref":"#/components/schemas/CustomFieldValue"},"type":"array"},"customer_portal_visible":{"default":false,"description":"Customer portal visible for this task","type":"boolean"},"due_date":{"description":"Due date for this task, in RFC 3339 format","format":"date-time","type":"string"},"milestone_id":{"description":"Milestone ID for this task","type":"string"},"parent_task_id":{"description":"Parent task ID, to create this task as a subtask","type":"string"},"project_id":{"description":"Project ID for this task","type":"string"},"status":{"$ref":"#/components/schemas/TaskStatus"},"title":{"description":"Title for this task","type":"string"}},"required":["title"],"type":"object"},"CustomFieldValue":{"description":"A custom field value to set. Custom fields not listed in a write request are left unchanged.","properties":{"slug":{"description":"The slug of the custom field.","type":"string"},"value":{"description":"The value of the custom field. Only to be used for single-valued custom fields. If unset, the custom field will be unset. If the custom field is a select field, the value must be the select option slug, which you can find from the GET /custom-fields endpoint. If the custom field is a relationship field, the value must be the related object ID.","type":"string"},"values":{"description":"The values of the custom field. Only to be used for multi-valued custom fields (ex. multiselect). Replaces the full selection; it does not add to or remove from the existing values. If unset, the custom field will be unset. If the custom field is a multiselect field, the values must be the select option slugs which you can find from the GET /custom-fields endpoint.","items":{"type":"string"},"type":"array"}},"title":"CustomFieldValue","type":"object"},"TaskStatus":{"type":"string"},"CreateTaskResponseBody":{"properties":{"data":{"$ref":"#/components/schemas/Task"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"required":["data","request_id"],"type":"object"},"Task":{"properties":{"account":{"$ref":"#/components/schemas/MiniAccount"},"assignee":{"$ref":"#/components/schemas/Actor"},"body_html":{"description":"The body of the task in HTML format.","type":"string"},"completed_at":{"description":"The completion time of the task in RFC3339 format.","format":"date-time","type":"string"},"created_at":{"description":"The created at time of the task.","format":"date-time","type":"string"},"custom_fields":{"additionalProperties":{"$ref":"#/components/schemas/CustomFieldValue"},"description":"Custom field values associated with the task, keyed by custom field slug.","nullable":true,"type":"object"},"customer_portal_visible":{"description":"The customer portal visible of the task.","type":"boolean"},"due_date":{"description":"The due date of the task in RFC3339 format.","format":"date-time","type":"string"},"external_issues":{"description":"The external product issues associated with the task, if any.","items":{"$ref":"#/components/schemas/ExternalIssue"},"type":"array"},"id":{"description":"The ID of the task.","type":"string"},"linked_issues":{"description":"The Pylon issues linked to the task that the current user can access, if any.","items":{"$ref":"#/components/schemas/MiniIssue"},"type":"array"},"milestone":{"$ref":"#/components/schemas/MiniMilestone"},"parent_task_id":{"description":"The ID of the parent task, if this is a subtask.","type":"string"},"project":{"$ref":"#/components/schemas/MiniProject"},"status":{"$ref":"#/components/schemas/TaskStatus"},"subtask_ids":{"description":"The IDs of subtasks belonging to this task.","items":{"type":"string"},"nullable":true,"type":"array"},"title":{"description":"The title of the task.","type":"string"},"updated_at":{"description":"The updated at time of the task.","format":"date-time","type":"string"}},"required":["body_html","created_at","customer_portal_visible","id","status","title","updated_at"],"type":"object"},"MiniAccount":{"properties":{"external_ids":{"description":"External IDs associated with the account.","items":{"$ref":"#/components/schemas/ExternalID"},"nullable":true,"type":"array"},"id":{"description":"The ID of the account.","type":"string"}},"required":["id"],"type":"object"},"ExternalID":{"properties":{"external_id":{"description":"The external ID. Must be unique per object type (ex. account).","type":"string"},"label":{"description":"The label of the external ID. Must be unique per object.","type":"string"}},"type":"object"},"Actor":{"properties":{"contact":{"$ref":"#/components/schemas/MiniContact"},"user":{"$ref":"#/components/schemas/MiniUser"}},"type":"object"},"MiniContact":{"properties":{"email":{"description":"The email of the contact.","type":"string"},"id":{"description":"The ID of the contact.","type":"string"}},"required":["id"],"type":"object"},"MiniUser":{"properties":{"email":{"description":"The email of the user.","type":"string"},"id":{"description":"The ID of the user.","type":"string"}},"required":["id"],"type":"object"},"ExternalIssue":{"properties":{"external_id":{"description":"The external ID of the external issue.\nJira: ID of the issue (autoincrementing number from 10000).\nGitHub: Owner/Repo/IssueID.\nLinear: ID of the issue (UUID).\nAsana: ID of the task (Long number).","type":"string"},"link":{"description":"Link to the product issue.","type":"string"},"source":{"description":"The source of the external issue.","type":"string"}},"required":["external_id","link","source"],"type":"object"},"MiniIssue":{"properties":{"id":{"description":"The ID of the issue.","type":"string"},"number":{"description":"The number of the issue.","format":"int64","type":"integer"},"title":{"description":"The title of the issue.","type":"string"}},"required":["id","number","title"],"type":"object"},"MiniMilestone":{"properties":{"id":{"description":"The ID of the milestone.","type":"string"}},"required":["id"],"type":"object"},"MiniProject":{"properties":{"id":{"description":"The ID of the project.","type":"string"}},"required":["id"],"type":"object"},"ErrorApiResponseBody":{"properties":{"code":{"description":"A stable machine-readable identifier for this failure, safe to branch on\ninstead of the message text. Omitted when the failure has no assigned code.\n\nKnown values: `recipients_suppressed`, `email_bounced`, `internal_issue_reply_not_allowed`, `duplicate_object`, `invalid_authorization_header`, `invalid_api_token`, `invalid_oauth_token`, `wrong_region_token`, `organization_deactivated`, `organization_suspended`, `permission_denied`, `oauth_not_permitted`, `rate_limited`, `not_found`, `method_not_allowed`, `payload_too_large`, `invalid_request_body`, `internal_error`, `invalid_webhook_credentials`, `organization_inactive`. This list is not exhaustive.","type":"string"},"errors":{"description":"The list of errors.","items":{"type":"string"},"type":"array"},"exists_id":{"description":"The ID of the object that already exists if this is a duplicate object error.","type":"string"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"required":["request_id"],"type":"object"}},"responses":{"CreateTaskResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTaskResponseBody"}}},"description":""},"BadRequestApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request was invalid or could not be completed."},"UnauthorizedApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request could not be authenticated for this API."},"ForbiddenApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The authenticated caller or organization is not allowed to access this endpoint or operation."},"ErrorApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":""},"TooManyRequestsApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request exceeded the applicable rate limit.","headers":{"Retry-After":{"description":"Seconds until the next request to this endpoint is permitted.","schema":{"format":"int64","type":"integer"}},"X-Retry-After":{"description":"Seconds until the full per-minute allowance is restored. Capacity returns gradually before then.","schema":{"format":"int64","type":"integer"}}}},"InternalServerErrorApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"An unexpected internal error occurred."}}},"paths":{"/tasks":{"post":{"description":"Creates a new task with a title and optional metadata.\n\n**Rate limit:** 300 requests per minute","operationId":"CreateTask","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTaskRequestBody"}}}},"responses":{"200":{"$ref":"#/components/responses/CreateTaskResponse"},"400":{"$ref":"#/components/responses/BadRequestApiResponse"},"401":{"$ref":"#/components/responses/UnauthorizedApiResponse"},"403":{"$ref":"#/components/responses/ForbiddenApiResponse"},"404":{"$ref":"#/components/responses/ErrorApiResponse"},"429":{"$ref":"#/components/responses/TooManyRequestsApiResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorApiResponse"}},"summary":"Create a task","tags":["tasks"]}}}} ``` ## Update a task > Updates an existing task. Only provided fields are modified.\ > \ > \*\*Rate limit:\*\* 300 requests per minute ```json {"openapi":"3.0.3","info":{"title":"Pylon API.","version":"1.0.0"},"tags":[],"servers":[{"description":"US region","url":"https://api.usepylon.com"},{"description":"EU region","url":"https://api.eu.usepylon.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"description":"Authorization: Bearer ","scheme":"bearer","type":"http"}},"schemas":{"UpdateTaskRequestBody":{"properties":{"assignee_id":{"description":"Assignee ID for this task","type":"string"},"body_html":{"description":"Body HTML for this task","type":"string"},"completed_at":{"description":"Completed at time for this task, in RFC 3339 format. The task must already have a completed status and completion date.","format":"date-time","type":"string"},"custom_fields":{"description":"An array of custom fields to be used on this task. Only passed in fields will be modified.","items":{"$ref":"#/components/schemas/CustomFieldValue"},"type":"array"},"customer_portal_visible":{"description":"Customer portal visible for this task","type":"boolean"},"due_date":{"description":"Due date for this task, in RFC 3339 format. Set to an empty string to clear it.","type":"string"},"milestone_id":{"description":"Milestone ID for this task","type":"string"},"project_id":{"description":"Project ID for this task","type":"string"},"status":{"$ref":"#/components/schemas/TaskStatus"},"title":{"description":"Title for this task","type":"string"}},"type":"object"},"CustomFieldValue":{"description":"A custom field value to set. Custom fields not listed in a write request are left unchanged.","properties":{"slug":{"description":"The slug of the custom field.","type":"string"},"value":{"description":"The value of the custom field. Only to be used for single-valued custom fields. If unset, the custom field will be unset. If the custom field is a select field, the value must be the select option slug, which you can find from the GET /custom-fields endpoint. If the custom field is a relationship field, the value must be the related object ID.","type":"string"},"values":{"description":"The values of the custom field. Only to be used for multi-valued custom fields (ex. multiselect). Replaces the full selection; it does not add to or remove from the existing values. If unset, the custom field will be unset. If the custom field is a multiselect field, the values must be the select option slugs which you can find from the GET /custom-fields endpoint.","items":{"type":"string"},"type":"array"}},"title":"CustomFieldValue","type":"object"},"TaskStatus":{"type":"string"},"UpdateTaskResponseBody":{"properties":{"data":{"$ref":"#/components/schemas/Task"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"required":["data","request_id"],"type":"object"},"Task":{"properties":{"account":{"$ref":"#/components/schemas/MiniAccount"},"assignee":{"$ref":"#/components/schemas/Actor"},"body_html":{"description":"The body of the task in HTML format.","type":"string"},"completed_at":{"description":"The completion time of the task in RFC3339 format.","format":"date-time","type":"string"},"created_at":{"description":"The created at time of the task.","format":"date-time","type":"string"},"custom_fields":{"additionalProperties":{"$ref":"#/components/schemas/CustomFieldValue"},"description":"Custom field values associated with the task, keyed by custom field slug.","nullable":true,"type":"object"},"customer_portal_visible":{"description":"The customer portal visible of the task.","type":"boolean"},"due_date":{"description":"The due date of the task in RFC3339 format.","format":"date-time","type":"string"},"external_issues":{"description":"The external product issues associated with the task, if any.","items":{"$ref":"#/components/schemas/ExternalIssue"},"type":"array"},"id":{"description":"The ID of the task.","type":"string"},"linked_issues":{"description":"The Pylon issues linked to the task that the current user can access, if any.","items":{"$ref":"#/components/schemas/MiniIssue"},"type":"array"},"milestone":{"$ref":"#/components/schemas/MiniMilestone"},"parent_task_id":{"description":"The ID of the parent task, if this is a subtask.","type":"string"},"project":{"$ref":"#/components/schemas/MiniProject"},"status":{"$ref":"#/components/schemas/TaskStatus"},"subtask_ids":{"description":"The IDs of subtasks belonging to this task.","items":{"type":"string"},"nullable":true,"type":"array"},"title":{"description":"The title of the task.","type":"string"},"updated_at":{"description":"The updated at time of the task.","format":"date-time","type":"string"}},"required":["body_html","created_at","customer_portal_visible","id","status","title","updated_at"],"type":"object"},"MiniAccount":{"properties":{"external_ids":{"description":"External IDs associated with the account.","items":{"$ref":"#/components/schemas/ExternalID"},"nullable":true,"type":"array"},"id":{"description":"The ID of the account.","type":"string"}},"required":["id"],"type":"object"},"ExternalID":{"properties":{"external_id":{"description":"The external ID. Must be unique per object type (ex. account).","type":"string"},"label":{"description":"The label of the external ID. Must be unique per object.","type":"string"}},"type":"object"},"Actor":{"properties":{"contact":{"$ref":"#/components/schemas/MiniContact"},"user":{"$ref":"#/components/schemas/MiniUser"}},"type":"object"},"MiniContact":{"properties":{"email":{"description":"The email of the contact.","type":"string"},"id":{"description":"The ID of the contact.","type":"string"}},"required":["id"],"type":"object"},"MiniUser":{"properties":{"email":{"description":"The email of the user.","type":"string"},"id":{"description":"The ID of the user.","type":"string"}},"required":["id"],"type":"object"},"ExternalIssue":{"properties":{"external_id":{"description":"The external ID of the external issue.\nJira: ID of the issue (autoincrementing number from 10000).\nGitHub: Owner/Repo/IssueID.\nLinear: ID of the issue (UUID).\nAsana: ID of the task (Long number).","type":"string"},"link":{"description":"Link to the product issue.","type":"string"},"source":{"description":"The source of the external issue.","type":"string"}},"required":["external_id","link","source"],"type":"object"},"MiniIssue":{"properties":{"id":{"description":"The ID of the issue.","type":"string"},"number":{"description":"The number of the issue.","format":"int64","type":"integer"},"title":{"description":"The title of the issue.","type":"string"}},"required":["id","number","title"],"type":"object"},"MiniMilestone":{"properties":{"id":{"description":"The ID of the milestone.","type":"string"}},"required":["id"],"type":"object"},"MiniProject":{"properties":{"id":{"description":"The ID of the project.","type":"string"}},"required":["id"],"type":"object"},"ErrorApiResponseBody":{"properties":{"code":{"description":"A stable machine-readable identifier for this failure, safe to branch on\ninstead of the message text. Omitted when the failure has no assigned code.\n\nKnown values: `recipients_suppressed`, `email_bounced`, `internal_issue_reply_not_allowed`, `duplicate_object`, `invalid_authorization_header`, `invalid_api_token`, `invalid_oauth_token`, `wrong_region_token`, `organization_deactivated`, `organization_suspended`, `permission_denied`, `oauth_not_permitted`, `rate_limited`, `not_found`, `method_not_allowed`, `payload_too_large`, `invalid_request_body`, `internal_error`, `invalid_webhook_credentials`, `organization_inactive`. This list is not exhaustive.","type":"string"},"errors":{"description":"The list of errors.","items":{"type":"string"},"type":"array"},"exists_id":{"description":"The ID of the object that already exists if this is a duplicate object error.","type":"string"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"required":["request_id"],"type":"object"}},"responses":{"UpdateTaskResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateTaskResponseBody"}}},"description":""},"BadRequestApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request was invalid or could not be completed."},"UnauthorizedApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request could not be authenticated for this API."},"ForbiddenApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The authenticated caller or organization is not allowed to access this endpoint or operation."},"ErrorApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":""},"TooManyRequestsApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request exceeded the applicable rate limit.","headers":{"Retry-After":{"description":"Seconds until the next request to this endpoint is permitted.","schema":{"format":"int64","type":"integer"}},"X-Retry-After":{"description":"Seconds until the full per-minute allowance is restored. Capacity returns gradually before then.","schema":{"format":"int64","type":"integer"}}}},"InternalServerErrorApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"An unexpected internal error occurred."}}},"paths":{"/tasks/{id}":{"patch":{"description":"Updates an existing task. Only provided fields are modified.\n\n**Rate limit:** 300 requests per minute","operationId":"UpdateTask","parameters":[{"description":"The ID of the task to update.","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateTaskRequestBody"}}}},"responses":{"200":{"$ref":"#/components/responses/UpdateTaskResponse"},"400":{"$ref":"#/components/responses/BadRequestApiResponse"},"401":{"$ref":"#/components/responses/UnauthorizedApiResponse"},"403":{"$ref":"#/components/responses/ForbiddenApiResponse"},"404":{"$ref":"#/components/responses/ErrorApiResponse"},"429":{"$ref":"#/components/responses/TooManyRequestsApiResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorApiResponse"}},"summary":"Update a task","tags":["tasks"]}}}} ``` ## Delete an existing task > Permanently deletes a task by ID.\ > \ > \*\*Rate limit:\*\* 120 requests per minute ```json {"openapi":"3.0.3","info":{"title":"Pylon API.","version":"1.0.0"},"tags":[],"servers":[{"description":"US region","url":"https://api.usepylon.com"},{"description":"EU region","url":"https://api.eu.usepylon.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"description":"Authorization: Bearer ","scheme":"bearer","type":"http"}},"responses":{"DeleteTaskResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteTaskResponseBody"}}},"description":""},"BadRequestApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request was invalid or could not be completed."},"UnauthorizedApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request could not be authenticated for this API."},"ForbiddenApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The authenticated caller or organization is not allowed to access this endpoint or operation."},"ErrorApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":""},"TooManyRequestsApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request exceeded the applicable rate limit.","headers":{"Retry-After":{"description":"Seconds until the next request to this endpoint is permitted.","schema":{"format":"int64","type":"integer"}},"X-Retry-After":{"description":"Seconds until the full per-minute allowance is restored. Capacity returns gradually before then.","schema":{"format":"int64","type":"integer"}}}},"InternalServerErrorApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"An unexpected internal error occurred."}},"schemas":{"DeleteTaskResponseBody":{"properties":{"request_id":{"description":"The request ID for tracking.","type":"string"}},"required":["request_id"],"type":"object"},"ErrorApiResponseBody":{"properties":{"code":{"description":"A stable machine-readable identifier for this failure, safe to branch on\ninstead of the message text. Omitted when the failure has no assigned code.\n\nKnown values: `recipients_suppressed`, `email_bounced`, `internal_issue_reply_not_allowed`, `duplicate_object`, `invalid_authorization_header`, `invalid_api_token`, `invalid_oauth_token`, `wrong_region_token`, `organization_deactivated`, `organization_suspended`, `permission_denied`, `oauth_not_permitted`, `rate_limited`, `not_found`, `method_not_allowed`, `payload_too_large`, `invalid_request_body`, `internal_error`, `invalid_webhook_credentials`, `organization_inactive`. This list is not exhaustive.","type":"string"},"errors":{"description":"The list of errors.","items":{"type":"string"},"type":"array"},"exists_id":{"description":"The ID of the object that already exists if this is a duplicate object error.","type":"string"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"required":["request_id"],"type":"object"}}},"paths":{"/tasks/{id}":{"delete":{"description":"Permanently deletes a task by ID.\n\n**Rate limit:** 120 requests per minute","operationId":"DeleteTask","parameters":[{"description":"The ID of the task to delete.","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/DeleteTaskResponse"},"400":{"$ref":"#/components/responses/BadRequestApiResponse"},"401":{"$ref":"#/components/responses/UnauthorizedApiResponse"},"403":{"$ref":"#/components/responses/ForbiddenApiResponse"},"404":{"$ref":"#/components/responses/ErrorApiResponse"},"429":{"$ref":"#/components/responses/TooManyRequestsApiResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorApiResponse"}},"summary":"Delete an existing task","tags":["tasks"]}}}} ``` ## Link or unlink an external issue to/from a task > By default, links the external issue. To unlink it, set the operation field to "unlink". Repeating the same link request is a successful no-op.\ > \ > \*\*Rate limit:\*\* 120 requests per minute ```json {"openapi":"3.0.3","info":{"title":"Pylon API.","version":"1.0.0"},"tags":[],"servers":[{"description":"US region","url":"https://api.usepylon.com"},{"description":"EU region","url":"https://api.eu.usepylon.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"description":"Authorization: Bearer ","scheme":"bearer","type":"http"}},"schemas":{"LinkTaskExternalIssueRequestBody":{"properties":{"external_issue_id":{"description":"The ID or human-readable key of the external issue in the source system.","type":"string"},"operation":{"description":"Operation to perform. Use \"link\" to link the issue (default) or \"unlink\" to unlink it.","type":"string"},"source":{"description":"The source system of the external issue (e.g., \"linear\", \"asana\", \"jira\", \"github\", \"shortcut\").","type":"string"}},"required":["source","external_issue_id"],"type":"object"},"LinkTaskExternalIssueResponseBody":{"properties":{"data":{"$ref":"#/components/schemas/Task"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"required":["data","request_id"],"type":"object"},"Task":{"properties":{"account":{"$ref":"#/components/schemas/MiniAccount"},"assignee":{"$ref":"#/components/schemas/Actor"},"body_html":{"description":"The body of the task in HTML format.","type":"string"},"completed_at":{"description":"The completion time of the task in RFC3339 format.","format":"date-time","type":"string"},"created_at":{"description":"The created at time of the task.","format":"date-time","type":"string"},"custom_fields":{"additionalProperties":{"$ref":"#/components/schemas/CustomFieldValue"},"description":"Custom field values associated with the task, keyed by custom field slug.","nullable":true,"type":"object"},"customer_portal_visible":{"description":"The customer portal visible of the task.","type":"boolean"},"due_date":{"description":"The due date of the task in RFC3339 format.","format":"date-time","type":"string"},"external_issues":{"description":"The external product issues associated with the task, if any.","items":{"$ref":"#/components/schemas/ExternalIssue"},"type":"array"},"id":{"description":"The ID of the task.","type":"string"},"linked_issues":{"description":"The Pylon issues linked to the task that the current user can access, if any.","items":{"$ref":"#/components/schemas/MiniIssue"},"type":"array"},"milestone":{"$ref":"#/components/schemas/MiniMilestone"},"parent_task_id":{"description":"The ID of the parent task, if this is a subtask.","type":"string"},"project":{"$ref":"#/components/schemas/MiniProject"},"status":{"$ref":"#/components/schemas/TaskStatus"},"subtask_ids":{"description":"The IDs of subtasks belonging to this task.","items":{"type":"string"},"nullable":true,"type":"array"},"title":{"description":"The title of the task.","type":"string"},"updated_at":{"description":"The updated at time of the task.","format":"date-time","type":"string"}},"required":["body_html","created_at","customer_portal_visible","id","status","title","updated_at"],"type":"object"},"MiniAccount":{"properties":{"external_ids":{"description":"External IDs associated with the account.","items":{"$ref":"#/components/schemas/ExternalID"},"nullable":true,"type":"array"},"id":{"description":"The ID of the account.","type":"string"}},"required":["id"],"type":"object"},"ExternalID":{"properties":{"external_id":{"description":"The external ID. Must be unique per object type (ex. account).","type":"string"},"label":{"description":"The label of the external ID. Must be unique per object.","type":"string"}},"type":"object"},"Actor":{"properties":{"contact":{"$ref":"#/components/schemas/MiniContact"},"user":{"$ref":"#/components/schemas/MiniUser"}},"type":"object"},"MiniContact":{"properties":{"email":{"description":"The email of the contact.","type":"string"},"id":{"description":"The ID of the contact.","type":"string"}},"required":["id"],"type":"object"},"MiniUser":{"properties":{"email":{"description":"The email of the user.","type":"string"},"id":{"description":"The ID of the user.","type":"string"}},"required":["id"],"type":"object"},"CustomFieldValue":{"description":"A custom field value to set. Custom fields not listed in a write request are left unchanged.","properties":{"slug":{"description":"The slug of the custom field.","type":"string"},"value":{"description":"The value of the custom field. Only to be used for single-valued custom fields. If unset, the custom field will be unset. If the custom field is a select field, the value must be the select option slug, which you can find from the GET /custom-fields endpoint. If the custom field is a relationship field, the value must be the related object ID.","type":"string"},"values":{"description":"The values of the custom field. Only to be used for multi-valued custom fields (ex. multiselect). Replaces the full selection; it does not add to or remove from the existing values. If unset, the custom field will be unset. If the custom field is a multiselect field, the values must be the select option slugs which you can find from the GET /custom-fields endpoint.","items":{"type":"string"},"type":"array"}},"title":"CustomFieldValue","type":"object"},"ExternalIssue":{"properties":{"external_id":{"description":"The external ID of the external issue.\nJira: ID of the issue (autoincrementing number from 10000).\nGitHub: Owner/Repo/IssueID.\nLinear: ID of the issue (UUID).\nAsana: ID of the task (Long number).","type":"string"},"link":{"description":"Link to the product issue.","type":"string"},"source":{"description":"The source of the external issue.","type":"string"}},"required":["external_id","link","source"],"type":"object"},"MiniIssue":{"properties":{"id":{"description":"The ID of the issue.","type":"string"},"number":{"description":"The number of the issue.","format":"int64","type":"integer"},"title":{"description":"The title of the issue.","type":"string"}},"required":["id","number","title"],"type":"object"},"MiniMilestone":{"properties":{"id":{"description":"The ID of the milestone.","type":"string"}},"required":["id"],"type":"object"},"MiniProject":{"properties":{"id":{"description":"The ID of the project.","type":"string"}},"required":["id"],"type":"object"},"TaskStatus":{"type":"string"},"ErrorApiResponseBody":{"properties":{"code":{"description":"A stable machine-readable identifier for this failure, safe to branch on\ninstead of the message text. Omitted when the failure has no assigned code.\n\nKnown values: `recipients_suppressed`, `email_bounced`, `internal_issue_reply_not_allowed`, `duplicate_object`, `invalid_authorization_header`, `invalid_api_token`, `invalid_oauth_token`, `wrong_region_token`, `organization_deactivated`, `organization_suspended`, `permission_denied`, `oauth_not_permitted`, `rate_limited`, `not_found`, `method_not_allowed`, `payload_too_large`, `invalid_request_body`, `internal_error`, `invalid_webhook_credentials`, `organization_inactive`. This list is not exhaustive.","type":"string"},"errors":{"description":"The list of errors.","items":{"type":"string"},"type":"array"},"exists_id":{"description":"The ID of the object that already exists if this is a duplicate object error.","type":"string"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"required":["request_id"],"type":"object"}},"responses":{"LinkTaskExternalIssueResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkTaskExternalIssueResponseBody"}}},"description":""},"BadRequestApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request was invalid or could not be completed."},"UnauthorizedApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request could not be authenticated for this API."},"ForbiddenApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The authenticated caller or organization is not allowed to access this endpoint or operation."},"ErrorApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":""},"TooManyRequestsApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request exceeded the applicable rate limit.","headers":{"Retry-After":{"description":"Seconds until the next request to this endpoint is permitted.","schema":{"format":"int64","type":"integer"}},"X-Retry-After":{"description":"Seconds until the full per-minute allowance is restored. Capacity returns gradually before then.","schema":{"format":"int64","type":"integer"}}}},"InternalServerErrorApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"An unexpected internal error occurred."}}},"paths":{"/tasks/{id}/external-issues":{"post":{"description":"By default, links the external issue. To unlink it, set the operation field to \"unlink\". Repeating the same link request is a successful no-op.\n\n**Rate limit:** 120 requests per minute","operationId":"LinkTaskExternalIssue","parameters":[{"description":"The ID of the task to link an external issue to.","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkTaskExternalIssueRequestBody"}}}},"responses":{"200":{"$ref":"#/components/responses/LinkTaskExternalIssueResponse"},"400":{"$ref":"#/components/responses/BadRequestApiResponse"},"401":{"$ref":"#/components/responses/UnauthorizedApiResponse"},"403":{"$ref":"#/components/responses/ForbiddenApiResponse"},"404":{"$ref":"#/components/responses/ErrorApiResponse"},"429":{"$ref":"#/components/responses/TooManyRequestsApiResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorApiResponse"}},"summary":"Link or unlink an external issue to/from a task","tags":["tasks"]}}}} ``` ## Link or unlink a Pylon issue to/from a task > Links the issue to the task by default. To unlink it, set the operation field to "unlink".\ > \ > \*\*Rate limit:\*\* 120 requests per minute ```json {"openapi":"3.0.3","info":{"title":"Pylon API.","version":"1.0.0"},"tags":[],"servers":[{"description":"US region","url":"https://api.usepylon.com"},{"description":"EU region","url":"https://api.eu.usepylon.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"description":"Authorization: Bearer ","scheme":"bearer","type":"http"}},"schemas":{"LinkTaskIssueRequestBody":{"properties":{"issue_id":{"description":"The ID of the Pylon issue.","type":"string"},"operation":{"description":"Operation to perform. Use \"link\" to link the issue (default) or \"unlink\" to unlink it.","type":"string"}},"required":["issue_id"],"type":"object"},"LinkTaskIssueResponseBody":{"properties":{"data":{"$ref":"#/components/schemas/Task"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"required":["data","request_id"],"type":"object"},"Task":{"properties":{"account":{"$ref":"#/components/schemas/MiniAccount"},"assignee":{"$ref":"#/components/schemas/Actor"},"body_html":{"description":"The body of the task in HTML format.","type":"string"},"completed_at":{"description":"The completion time of the task in RFC3339 format.","format":"date-time","type":"string"},"created_at":{"description":"The created at time of the task.","format":"date-time","type":"string"},"custom_fields":{"additionalProperties":{"$ref":"#/components/schemas/CustomFieldValue"},"description":"Custom field values associated with the task, keyed by custom field slug.","nullable":true,"type":"object"},"customer_portal_visible":{"description":"The customer portal visible of the task.","type":"boolean"},"due_date":{"description":"The due date of the task in RFC3339 format.","format":"date-time","type":"string"},"external_issues":{"description":"The external product issues associated with the task, if any.","items":{"$ref":"#/components/schemas/ExternalIssue"},"type":"array"},"id":{"description":"The ID of the task.","type":"string"},"linked_issues":{"description":"The Pylon issues linked to the task that the current user can access, if any.","items":{"$ref":"#/components/schemas/MiniIssue"},"type":"array"},"milestone":{"$ref":"#/components/schemas/MiniMilestone"},"parent_task_id":{"description":"The ID of the parent task, if this is a subtask.","type":"string"},"project":{"$ref":"#/components/schemas/MiniProject"},"status":{"$ref":"#/components/schemas/TaskStatus"},"subtask_ids":{"description":"The IDs of subtasks belonging to this task.","items":{"type":"string"},"nullable":true,"type":"array"},"title":{"description":"The title of the task.","type":"string"},"updated_at":{"description":"The updated at time of the task.","format":"date-time","type":"string"}},"required":["body_html","created_at","customer_portal_visible","id","status","title","updated_at"],"type":"object"},"MiniAccount":{"properties":{"external_ids":{"description":"External IDs associated with the account.","items":{"$ref":"#/components/schemas/ExternalID"},"nullable":true,"type":"array"},"id":{"description":"The ID of the account.","type":"string"}},"required":["id"],"type":"object"},"ExternalID":{"properties":{"external_id":{"description":"The external ID. Must be unique per object type (ex. account).","type":"string"},"label":{"description":"The label of the external ID. Must be unique per object.","type":"string"}},"type":"object"},"Actor":{"properties":{"contact":{"$ref":"#/components/schemas/MiniContact"},"user":{"$ref":"#/components/schemas/MiniUser"}},"type":"object"},"MiniContact":{"properties":{"email":{"description":"The email of the contact.","type":"string"},"id":{"description":"The ID of the contact.","type":"string"}},"required":["id"],"type":"object"},"MiniUser":{"properties":{"email":{"description":"The email of the user.","type":"string"},"id":{"description":"The ID of the user.","type":"string"}},"required":["id"],"type":"object"},"CustomFieldValue":{"description":"A custom field value to set. Custom fields not listed in a write request are left unchanged.","properties":{"slug":{"description":"The slug of the custom field.","type":"string"},"value":{"description":"The value of the custom field. Only to be used for single-valued custom fields. If unset, the custom field will be unset. If the custom field is a select field, the value must be the select option slug, which you can find from the GET /custom-fields endpoint. If the custom field is a relationship field, the value must be the related object ID.","type":"string"},"values":{"description":"The values of the custom field. Only to be used for multi-valued custom fields (ex. multiselect). Replaces the full selection; it does not add to or remove from the existing values. If unset, the custom field will be unset. If the custom field is a multiselect field, the values must be the select option slugs which you can find from the GET /custom-fields endpoint.","items":{"type":"string"},"type":"array"}},"title":"CustomFieldValue","type":"object"},"ExternalIssue":{"properties":{"external_id":{"description":"The external ID of the external issue.\nJira: ID of the issue (autoincrementing number from 10000).\nGitHub: Owner/Repo/IssueID.\nLinear: ID of the issue (UUID).\nAsana: ID of the task (Long number).","type":"string"},"link":{"description":"Link to the product issue.","type":"string"},"source":{"description":"The source of the external issue.","type":"string"}},"required":["external_id","link","source"],"type":"object"},"MiniIssue":{"properties":{"id":{"description":"The ID of the issue.","type":"string"},"number":{"description":"The number of the issue.","format":"int64","type":"integer"},"title":{"description":"The title of the issue.","type":"string"}},"required":["id","number","title"],"type":"object"},"MiniMilestone":{"properties":{"id":{"description":"The ID of the milestone.","type":"string"}},"required":["id"],"type":"object"},"MiniProject":{"properties":{"id":{"description":"The ID of the project.","type":"string"}},"required":["id"],"type":"object"},"TaskStatus":{"type":"string"},"ErrorApiResponseBody":{"properties":{"code":{"description":"A stable machine-readable identifier for this failure, safe to branch on\ninstead of the message text. Omitted when the failure has no assigned code.\n\nKnown values: `recipients_suppressed`, `email_bounced`, `internal_issue_reply_not_allowed`, `duplicate_object`, `invalid_authorization_header`, `invalid_api_token`, `invalid_oauth_token`, `wrong_region_token`, `organization_deactivated`, `organization_suspended`, `permission_denied`, `oauth_not_permitted`, `rate_limited`, `not_found`, `method_not_allowed`, `payload_too_large`, `invalid_request_body`, `internal_error`, `invalid_webhook_credentials`, `organization_inactive`. This list is not exhaustive.","type":"string"},"errors":{"description":"The list of errors.","items":{"type":"string"},"type":"array"},"exists_id":{"description":"The ID of the object that already exists if this is a duplicate object error.","type":"string"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"required":["request_id"],"type":"object"}},"responses":{"LinkTaskIssueResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkTaskIssueResponseBody"}}},"description":""},"BadRequestApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request was invalid or could not be completed."},"UnauthorizedApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request could not be authenticated for this API."},"ForbiddenApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The authenticated caller or organization is not allowed to access this endpoint or operation."},"ErrorApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":""},"TooManyRequestsApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request exceeded the applicable rate limit.","headers":{"Retry-After":{"description":"Seconds until the next request to this endpoint is permitted.","schema":{"format":"int64","type":"integer"}},"X-Retry-After":{"description":"Seconds until the full per-minute allowance is restored. Capacity returns gradually before then.","schema":{"format":"int64","type":"integer"}}}},"InternalServerErrorApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"An unexpected internal error occurred."}}},"paths":{"/tasks/{id}/issues":{"post":{"description":"Links the issue to the task by default. To unlink it, set the operation field to \"unlink\".\n\n**Rate limit:** 120 requests per minute","operationId":"LinkTaskIssue","parameters":[{"description":"The ID of the task to link a Pylon issue to.","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkTaskIssueRequestBody"}}}},"responses":{"200":{"$ref":"#/components/responses/LinkTaskIssueResponse"},"400":{"$ref":"#/components/responses/BadRequestApiResponse"},"401":{"$ref":"#/components/responses/UnauthorizedApiResponse"},"403":{"$ref":"#/components/responses/ForbiddenApiResponse"},"404":{"$ref":"#/components/responses/ErrorApiResponse"},"429":{"$ref":"#/components/responses/TooManyRequestsApiResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorApiResponse"}},"summary":"Link or unlink a Pylon issue to/from a task","tags":["tasks"]}}}} ``` ## Get all task statuses > Returns all task statuses for the organization.\ > \ > \*\*Rate limit:\*\* 30 requests per minute ```json {"openapi":"3.0.3","info":{"title":"Pylon API.","version":"1.0.0"},"tags":[],"servers":[{"description":"US region","url":"https://api.usepylon.com"},{"description":"EU region","url":"https://api.eu.usepylon.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"description":"Authorization: Bearer ","scheme":"bearer","type":"http"}},"responses":{"GetTaskStatusesResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetTaskStatusesResponseBody"}}},"description":""},"UnauthorizedApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request could not be authenticated for this API."},"ForbiddenApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The authenticated caller or organization is not allowed to access this endpoint or operation."},"TooManyRequestsApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request exceeded the applicable rate limit.","headers":{"Retry-After":{"description":"Seconds until the next request to this endpoint is permitted.","schema":{"format":"int64","type":"integer"}},"X-Retry-After":{"description":"Seconds until the full per-minute allowance is restored. Capacity returns gradually before then.","schema":{"format":"int64","type":"integer"}}}},"InternalServerErrorApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"An unexpected internal error occurred."}},"schemas":{"GetTaskStatusesResponseBody":{"properties":{"data":{"description":"The data payload of the response.","items":{"$ref":"#/components/schemas/TaskStatusDetails"},"type":"array"},"pagination":{"$ref":"#/components/schemas/Pagination"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"required":["data","request_id"],"type":"object"},"TaskStatusDetails":{"properties":{"category":{"description":"The category of the task status.","type":"string"},"is_archived":{"description":"Indicates if the task status is archived.","type":"boolean"},"is_default_status":{"description":"Indicates if the task status is a default status.","type":"boolean"},"label":{"description":"The label of the task status.","type":"string"},"slug":{"description":"The slug of the task status.","type":"string"}},"required":["category","is_archived","is_default_status","label","slug"],"type":"object"},"Pagination":{"description":"Pagination information for list responses. Absent when there are no more results.","properties":{"cursor":{"description":"The cursor for the next page of results.","type":"string"},"has_next_page":{"description":"Indicates if there is a next page of results.","type":"boolean"}},"required":["cursor","has_next_page"],"title":"Pagination","type":"object"},"ErrorApiResponseBody":{"properties":{"code":{"description":"A stable machine-readable identifier for this failure, safe to branch on\ninstead of the message text. Omitted when the failure has no assigned code.\n\nKnown values: `recipients_suppressed`, `email_bounced`, `internal_issue_reply_not_allowed`, `duplicate_object`, `invalid_authorization_header`, `invalid_api_token`, `invalid_oauth_token`, `wrong_region_token`, `organization_deactivated`, `organization_suspended`, `permission_denied`, `oauth_not_permitted`, `rate_limited`, `not_found`, `method_not_allowed`, `payload_too_large`, `invalid_request_body`, `internal_error`, `invalid_webhook_credentials`, `organization_inactive`. This list is not exhaustive.","type":"string"},"errors":{"description":"The list of errors.","items":{"type":"string"},"type":"array"},"exists_id":{"description":"The ID of the object that already exists if this is a duplicate object error.","type":"string"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"required":["request_id"],"type":"object"}}},"paths":{"/task-statuses":{"get":{"description":"Returns all task statuses for the organization.\n\n**Rate limit:** 30 requests per minute","operationId":"GetTaskStatuses","responses":{"200":{"$ref":"#/components/responses/GetTaskStatusesResponse"},"401":{"$ref":"#/components/responses/UnauthorizedApiResponse"},"403":{"$ref":"#/components/responses/ForbiddenApiResponse"},"429":{"$ref":"#/components/responses/TooManyRequestsApiResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorApiResponse"}},"summary":"Get all task statuses","tags":["task-statuses"]}}}} ``` ## Get a project by its ID > Returns a single project by ID.\ > \ > \*\*Rate limit:\*\* 300 requests per minute ```json {"openapi":"3.0.3","info":{"title":"Pylon API.","version":"1.0.0"},"tags":[],"servers":[{"description":"US region","url":"https://api.usepylon.com"},{"description":"EU region","url":"https://api.eu.usepylon.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"description":"Authorization: Bearer ","scheme":"bearer","type":"http"}},"responses":{"GetProjectResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetProjectResponseBody"}}},"description":""},"BadRequestApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request was invalid or could not be completed."},"UnauthorizedApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request could not be authenticated for this API."},"ForbiddenApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The authenticated caller or organization is not allowed to access this endpoint or operation."},"ErrorApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":""},"TooManyRequestsApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request exceeded the applicable rate limit.","headers":{"Retry-After":{"description":"Seconds until the next request to this endpoint is permitted.","schema":{"format":"int64","type":"integer"}},"X-Retry-After":{"description":"Seconds until the full per-minute allowance is restored. Capacity returns gradually before then.","schema":{"format":"int64","type":"integer"}}}},"InternalServerErrorApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"An unexpected internal error occurred."}},"schemas":{"GetProjectResponseBody":{"properties":{"data":{"$ref":"#/components/schemas/Project"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"required":["data","request_id"],"type":"object"},"Project":{"properties":{"account":{"$ref":"#/components/schemas/MiniAccount"},"archived_at":{"description":"The archived at time of the project in RFC3339 format.","format":"date-time","type":"string"},"created_at":{"description":"The created at time of the project.","format":"date-time","type":"string"},"custom_fields":{"additionalProperties":{"$ref":"#/components/schemas/CustomFieldValue"},"description":"Custom fields for this project, keyed by slug.","nullable":true,"type":"object"},"customer_portal_visible":{"description":"The customer portal visible of the project.","type":"boolean"},"description_html":{"description":"The description of the project in HTML format.","type":"string"},"end_date":{"description":"The end date of the project in RFC3339 format.","format":"date-time","type":"string"},"id":{"description":"The ID of the project.","type":"string"},"is_archived":{"description":"Whether the project is archived.","type":"boolean"},"name":{"description":"The name of the project.","type":"string"},"owner_id":{"description":"The owner ID of the project.","type":"string"},"progress":{"description":"The fraction of completed tasks, from 0 to 1.","format":"double","type":"number"},"project_template":{"$ref":"#/components/schemas/MiniProjectTemplate"},"start_date":{"description":"The start date of the project in RFC3339 format.","format":"date-time","type":"string"},"status":{"description":"The status of the project. One of not_started, in_progress, or completed.\n\nKnown values: `not_started`, `in_progress`, `completed`. This list is not exhaustive.","type":"string"},"updated_at":{"description":"The updated at time of the project.","format":"date-time","type":"string"}},"required":["created_at","customer_portal_visible","id","is_archived","name","progress","status","updated_at"],"type":"object"},"MiniAccount":{"properties":{"external_ids":{"description":"External IDs associated with the account.","items":{"$ref":"#/components/schemas/ExternalID"},"nullable":true,"type":"array"},"id":{"description":"The ID of the account.","type":"string"}},"required":["id"],"type":"object"},"ExternalID":{"properties":{"external_id":{"description":"The external ID. Must be unique per object type (ex. account).","type":"string"},"label":{"description":"The label of the external ID. Must be unique per object.","type":"string"}},"type":"object"},"CustomFieldValue":{"description":"A custom field value to set. Custom fields not listed in a write request are left unchanged.","properties":{"slug":{"description":"The slug of the custom field.","type":"string"},"value":{"description":"The value of the custom field. Only to be used for single-valued custom fields. If unset, the custom field will be unset. If the custom field is a select field, the value must be the select option slug, which you can find from the GET /custom-fields endpoint. If the custom field is a relationship field, the value must be the related object ID.","type":"string"},"values":{"description":"The values of the custom field. Only to be used for multi-valued custom fields (ex. multiselect). Replaces the full selection; it does not add to or remove from the existing values. If unset, the custom field will be unset. If the custom field is a multiselect field, the values must be the select option slugs which you can find from the GET /custom-fields endpoint.","items":{"type":"string"},"type":"array"}},"title":"CustomFieldValue","type":"object"},"MiniProjectTemplate":{"properties":{"id":{"description":"The ID of the project template.","type":"string"}},"required":["id"],"type":"object"},"ErrorApiResponseBody":{"properties":{"code":{"description":"A stable machine-readable identifier for this failure, safe to branch on\ninstead of the message text. Omitted when the failure has no assigned code.\n\nKnown values: `recipients_suppressed`, `email_bounced`, `internal_issue_reply_not_allowed`, `duplicate_object`, `invalid_authorization_header`, `invalid_api_token`, `invalid_oauth_token`, `wrong_region_token`, `organization_deactivated`, `organization_suspended`, `permission_denied`, `oauth_not_permitted`, `rate_limited`, `not_found`, `method_not_allowed`, `payload_too_large`, `invalid_request_body`, `internal_error`, `invalid_webhook_credentials`, `organization_inactive`. This list is not exhaustive.","type":"string"},"errors":{"description":"The list of errors.","items":{"type":"string"},"type":"array"},"exists_id":{"description":"The ID of the object that already exists if this is a duplicate object error.","type":"string"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"required":["request_id"],"type":"object"}}},"paths":{"/projects/{id}":{"get":{"description":"Returns a single project by ID.\n\n**Rate limit:** 300 requests per minute","operationId":"GetProject","parameters":[{"description":"The ID of the project to fetch.","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/GetProjectResponse"},"400":{"$ref":"#/components/responses/BadRequestApiResponse"},"401":{"$ref":"#/components/responses/UnauthorizedApiResponse"},"403":{"$ref":"#/components/responses/ForbiddenApiResponse"},"404":{"$ref":"#/components/responses/ErrorApiResponse"},"429":{"$ref":"#/components/responses/TooManyRequestsApiResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorApiResponse"}},"summary":"Get a project by its ID","tags":["projects"]}}}} ``` ## Search for projects by a given filter > Filterable fields and their allowed operators:\ > \ > Field | Allowed operators |\ > \--- | --- |\ > \`account\_id\` | \`equals\`, \`in\`, \`not\_in\`, \`is\_set\` |\ > \`status\` | \`equals\`, \`in\`, \`not\_in\` |\ > \`owner\_id\` | \`equals\`, \`in\`, \`not\_in\`, \`is\_set\`, \`is\_unset\` |\ > \`is\_archived\` | \`equals\` |\ > \`created\_at\` | \`time\_is\_after\`, \`time\_is\_before\`, \`time\_range\` |\ > \`updated\_at\` | \`time\_is\_after\`, \`time\_is\_before\`, \`time\_range\` |\ > \ > Timestamp values use RFC3339 format. Valid \`status\` values are \`not\_started\`, \`in\_progress\`, and \`completed\`. For custom fields, pass the field slug as \`field\`.\ > \ > \*\*Rate limit:\*\* 120 requests per minute ```json {"openapi":"3.0.3","info":{"title":"Pylon API.","version":"1.0.0"},"tags":[],"servers":[{"description":"US region","url":"https://api.usepylon.com"},{"description":"EU region","url":"https://api.eu.usepylon.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"description":"Authorization: Bearer ","scheme":"bearer","type":"http"}},"schemas":{"SearchProjectsRequest":{"properties":{"cursor":{"description":"The cursor to use for pagination.","type":"string"},"filter":{"$ref":"#/components/schemas/Filter"},"limit":{"description":"The number of projects to fetch. Defaults to 100. Must be greater than 0 and less than 1000.","format":"int64","type":"integer"}},"type":"object"},"Filter":{"properties":{"field":{"description":"The field for this filter. For allowed fields, see the documentation for\nthe specific endpoint you are using.\nFor non-compound filters (any operators other than \"and\" or \"or\"),\nfield must be set, along with either value or values, depending on the operator.","type":"string"},"operator":{"description":"The operator for this filter.","enum":["equals","not_equals","contains","does_not_contain","in","not_in","and","or","time_is_after","time_is_before","time_range","string_contains","string_does_not_contain","is_set","is_unset","greater_than","less_than","greater_than_or_equals","less_than_or_equals","includes_all_of","starts_with","ends_with"],"type":"string"},"subfilters":{"description":"Sub-filters for this filter. Valid only when operator is \"and\" or \"or\".\nThe maximum allowed depth for a tree of filters is 3, counting the top-level filter.","items":{"$ref":"#/components/schemas/Filter"},"type":"array"},"value":{"description":"The value for this filter. Used by single-valued operators: \"equals\", \"not_equals\",\n\"contains\", \"does_not_contain\", \"string_contains\", \"string_does_not_contain\",\n\"starts_with\", \"ends_with\", \"time_is_after\", \"time_is_before\", \"greater_than\",\n\"less_than\", \"greater_than_or_equals\", and \"less_than_or_equals\".","type":"string"},"values":{"description":"The values for this filter. Used by multi-valued operators: \"in\", \"not_in\", and\n\"includes_all_of\". For \"time_range\", set to [start, end].","items":{"type":"string"},"type":"array"}},"required":["operator"],"type":"object"},"SearchProjectsResponseBody":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Project"},"type":"array"},"pagination":{"$ref":"#/components/schemas/Pagination"},"request_id":{"type":"string"}},"required":["data","request_id"],"type":"object"},"Project":{"properties":{"account":{"$ref":"#/components/schemas/MiniAccount"},"archived_at":{"description":"The archived at time of the project in RFC3339 format.","format":"date-time","type":"string"},"created_at":{"description":"The created at time of the project.","format":"date-time","type":"string"},"custom_fields":{"additionalProperties":{"$ref":"#/components/schemas/CustomFieldValue"},"description":"Custom fields for this project, keyed by slug.","nullable":true,"type":"object"},"customer_portal_visible":{"description":"The customer portal visible of the project.","type":"boolean"},"description_html":{"description":"The description of the project in HTML format.","type":"string"},"end_date":{"description":"The end date of the project in RFC3339 format.","format":"date-time","type":"string"},"id":{"description":"The ID of the project.","type":"string"},"is_archived":{"description":"Whether the project is archived.","type":"boolean"},"name":{"description":"The name of the project.","type":"string"},"owner_id":{"description":"The owner ID of the project.","type":"string"},"progress":{"description":"The fraction of completed tasks, from 0 to 1.","format":"double","type":"number"},"project_template":{"$ref":"#/components/schemas/MiniProjectTemplate"},"start_date":{"description":"The start date of the project in RFC3339 format.","format":"date-time","type":"string"},"status":{"description":"The status of the project. One of not_started, in_progress, or completed.\n\nKnown values: `not_started`, `in_progress`, `completed`. This list is not exhaustive.","type":"string"},"updated_at":{"description":"The updated at time of the project.","format":"date-time","type":"string"}},"required":["created_at","customer_portal_visible","id","is_archived","name","progress","status","updated_at"],"type":"object"},"MiniAccount":{"properties":{"external_ids":{"description":"External IDs associated with the account.","items":{"$ref":"#/components/schemas/ExternalID"},"nullable":true,"type":"array"},"id":{"description":"The ID of the account.","type":"string"}},"required":["id"],"type":"object"},"ExternalID":{"properties":{"external_id":{"description":"The external ID. Must be unique per object type (ex. account).","type":"string"},"label":{"description":"The label of the external ID. Must be unique per object.","type":"string"}},"type":"object"},"CustomFieldValue":{"description":"A custom field value to set. Custom fields not listed in a write request are left unchanged.","properties":{"slug":{"description":"The slug of the custom field.","type":"string"},"value":{"description":"The value of the custom field. Only to be used for single-valued custom fields. If unset, the custom field will be unset. If the custom field is a select field, the value must be the select option slug, which you can find from the GET /custom-fields endpoint. If the custom field is a relationship field, the value must be the related object ID.","type":"string"},"values":{"description":"The values of the custom field. Only to be used for multi-valued custom fields (ex. multiselect). Replaces the full selection; it does not add to or remove from the existing values. If unset, the custom field will be unset. If the custom field is a multiselect field, the values must be the select option slugs which you can find from the GET /custom-fields endpoint.","items":{"type":"string"},"type":"array"}},"title":"CustomFieldValue","type":"object"},"MiniProjectTemplate":{"properties":{"id":{"description":"The ID of the project template.","type":"string"}},"required":["id"],"type":"object"},"Pagination":{"description":"Pagination information for list responses. Absent when there are no more results.","properties":{"cursor":{"description":"The cursor for the next page of results.","type":"string"},"has_next_page":{"description":"Indicates if there is a next page of results.","type":"boolean"}},"required":["cursor","has_next_page"],"title":"Pagination","type":"object"},"ErrorApiResponseBody":{"properties":{"code":{"description":"A stable machine-readable identifier for this failure, safe to branch on\ninstead of the message text. Omitted when the failure has no assigned code.\n\nKnown values: `recipients_suppressed`, `email_bounced`, `internal_issue_reply_not_allowed`, `duplicate_object`, `invalid_authorization_header`, `invalid_api_token`, `invalid_oauth_token`, `wrong_region_token`, `organization_deactivated`, `organization_suspended`, `permission_denied`, `oauth_not_permitted`, `rate_limited`, `not_found`, `method_not_allowed`, `payload_too_large`, `invalid_request_body`, `internal_error`, `invalid_webhook_credentials`, `organization_inactive`. This list is not exhaustive.","type":"string"},"errors":{"description":"The list of errors.","items":{"type":"string"},"type":"array"},"exists_id":{"description":"The ID of the object that already exists if this is a duplicate object error.","type":"string"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"required":["request_id"],"type":"object"}},"responses":{"SearchProjectsResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchProjectsResponseBody"}}},"description":""},"BadRequestApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request was invalid or could not be completed."},"UnauthorizedApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request could not be authenticated for this API."},"ForbiddenApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The authenticated caller or organization is not allowed to access this endpoint or operation."},"TooManyRequestsApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request exceeded the applicable rate limit.","headers":{"Retry-After":{"description":"Seconds until the next request to this endpoint is permitted.","schema":{"format":"int64","type":"integer"}},"X-Retry-After":{"description":"Seconds until the full per-minute allowance is restored. Capacity returns gradually before then.","schema":{"format":"int64","type":"integer"}}}},"InternalServerErrorApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"An unexpected internal error occurred."}}},"paths":{"/projects/search":{"post":{"description":"Filterable fields and their allowed operators:\n\n Field | Allowed operators |\n --- | --- |\n `account_id` | `equals`, `in`, `not_in`, `is_set` |\n `status` | `equals`, `in`, `not_in` |\n `owner_id` | `equals`, `in`, `not_in`, `is_set`, `is_unset` |\n `is_archived` | `equals` |\n `created_at` | `time_is_after`, `time_is_before`, `time_range` |\n `updated_at` | `time_is_after`, `time_is_before`, `time_range` |\n\nTimestamp values use RFC3339 format. Valid `status` values are `not_started`, `in_progress`, and `completed`. For custom fields, pass the field slug as `field`.\n\n**Rate limit:** 120 requests per minute","operationId":"SearchProjects","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchProjectsRequest"}}}},"responses":{"200":{"$ref":"#/components/responses/SearchProjectsResponse"},"400":{"$ref":"#/components/responses/BadRequestApiResponse"},"401":{"$ref":"#/components/responses/UnauthorizedApiResponse"},"403":{"$ref":"#/components/responses/ForbiddenApiResponse"},"429":{"$ref":"#/components/responses/TooManyRequestsApiResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorApiResponse"}},"summary":"Search for projects by a given filter","tags":["projects"]}}}} ``` ## Update a project > Updates an existing project. Only provided fields are modified.\ > \ > \*\*Rate limit:\*\* 300 requests per minute ```json {"openapi":"3.0.3","info":{"title":"Pylon API.","version":"1.0.0"},"tags":[],"servers":[{"description":"US region","url":"https://api.usepylon.com"},{"description":"EU region","url":"https://api.eu.usepylon.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"description":"Authorization: Bearer ","scheme":"bearer","type":"http"}},"schemas":{"UpdateProjectRequestBody":{"properties":{"custom_fields":{"description":"An array of custom fields to be used on this project. Only passed in fields will be modified.","items":{"$ref":"#/components/schemas/CustomFieldValue"},"type":"array"},"customer_portal_visible":{"description":"Customer portal visible for this project","type":"boolean"},"description_html":{"description":"Description HTML for this project","type":"string"},"end_date":{"description":"End date for this project, in RFC 3339 format. Set to an empty string to clear it.","type":"string"},"is_archived":{"description":"Whether the project is archived","type":"boolean"},"name":{"description":"Name for this project","type":"string"},"owner_id":{"description":"Owner ID for this project","type":"string"},"start_date":{"description":"Start date for this project, in RFC 3339 format. Set to an empty string to clear it.","type":"string"}},"type":"object"},"CustomFieldValue":{"description":"A custom field value to set. Custom fields not listed in a write request are left unchanged.","properties":{"slug":{"description":"The slug of the custom field.","type":"string"},"value":{"description":"The value of the custom field. Only to be used for single-valued custom fields. If unset, the custom field will be unset. If the custom field is a select field, the value must be the select option slug, which you can find from the GET /custom-fields endpoint. If the custom field is a relationship field, the value must be the related object ID.","type":"string"},"values":{"description":"The values of the custom field. Only to be used for multi-valued custom fields (ex. multiselect). Replaces the full selection; it does not add to or remove from the existing values. If unset, the custom field will be unset. If the custom field is a multiselect field, the values must be the select option slugs which you can find from the GET /custom-fields endpoint.","items":{"type":"string"},"type":"array"}},"title":"CustomFieldValue","type":"object"},"UpdateProjectResponseBody":{"properties":{"data":{"$ref":"#/components/schemas/Project"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"required":["data","request_id"],"type":"object"},"Project":{"properties":{"account":{"$ref":"#/components/schemas/MiniAccount"},"archived_at":{"description":"The archived at time of the project in RFC3339 format.","format":"date-time","type":"string"},"created_at":{"description":"The created at time of the project.","format":"date-time","type":"string"},"custom_fields":{"additionalProperties":{"$ref":"#/components/schemas/CustomFieldValue"},"description":"Custom fields for this project, keyed by slug.","nullable":true,"type":"object"},"customer_portal_visible":{"description":"The customer portal visible of the project.","type":"boolean"},"description_html":{"description":"The description of the project in HTML format.","type":"string"},"end_date":{"description":"The end date of the project in RFC3339 format.","format":"date-time","type":"string"},"id":{"description":"The ID of the project.","type":"string"},"is_archived":{"description":"Whether the project is archived.","type":"boolean"},"name":{"description":"The name of the project.","type":"string"},"owner_id":{"description":"The owner ID of the project.","type":"string"},"progress":{"description":"The fraction of completed tasks, from 0 to 1.","format":"double","type":"number"},"project_template":{"$ref":"#/components/schemas/MiniProjectTemplate"},"start_date":{"description":"The start date of the project in RFC3339 format.","format":"date-time","type":"string"},"status":{"description":"The status of the project. One of not_started, in_progress, or completed.\n\nKnown values: `not_started`, `in_progress`, `completed`. This list is not exhaustive.","type":"string"},"updated_at":{"description":"The updated at time of the project.","format":"date-time","type":"string"}},"required":["created_at","customer_portal_visible","id","is_archived","name","progress","status","updated_at"],"type":"object"},"MiniAccount":{"properties":{"external_ids":{"description":"External IDs associated with the account.","items":{"$ref":"#/components/schemas/ExternalID"},"nullable":true,"type":"array"},"id":{"description":"The ID of the account.","type":"string"}},"required":["id"],"type":"object"},"ExternalID":{"properties":{"external_id":{"description":"The external ID. Must be unique per object type (ex. account).","type":"string"},"label":{"description":"The label of the external ID. Must be unique per object.","type":"string"}},"type":"object"},"MiniProjectTemplate":{"properties":{"id":{"description":"The ID of the project template.","type":"string"}},"required":["id"],"type":"object"},"ErrorApiResponseBody":{"properties":{"code":{"description":"A stable machine-readable identifier for this failure, safe to branch on\ninstead of the message text. Omitted when the failure has no assigned code.\n\nKnown values: `recipients_suppressed`, `email_bounced`, `internal_issue_reply_not_allowed`, `duplicate_object`, `invalid_authorization_header`, `invalid_api_token`, `invalid_oauth_token`, `wrong_region_token`, `organization_deactivated`, `organization_suspended`, `permission_denied`, `oauth_not_permitted`, `rate_limited`, `not_found`, `method_not_allowed`, `payload_too_large`, `invalid_request_body`, `internal_error`, `invalid_webhook_credentials`, `organization_inactive`. This list is not exhaustive.","type":"string"},"errors":{"description":"The list of errors.","items":{"type":"string"},"type":"array"},"exists_id":{"description":"The ID of the object that already exists if this is a duplicate object error.","type":"string"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"required":["request_id"],"type":"object"}},"responses":{"UpdateProjectResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateProjectResponseBody"}}},"description":""},"BadRequestApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request was invalid or could not be completed."},"UnauthorizedApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request could not be authenticated for this API."},"ForbiddenApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The authenticated caller or organization is not allowed to access this endpoint or operation."},"ErrorApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":""},"TooManyRequestsApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request exceeded the applicable rate limit.","headers":{"Retry-After":{"description":"Seconds until the next request to this endpoint is permitted.","schema":{"format":"int64","type":"integer"}},"X-Retry-After":{"description":"Seconds until the full per-minute allowance is restored. Capacity returns gradually before then.","schema":{"format":"int64","type":"integer"}}}},"InternalServerErrorApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"An unexpected internal error occurred."}}},"paths":{"/projects/{id}":{"patch":{"description":"Updates an existing project. Only provided fields are modified.\n\n**Rate limit:** 300 requests per minute","operationId":"UpdateProject","parameters":[{"description":"The ID of the project to update.","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateProjectRequestBody"}}}},"responses":{"200":{"$ref":"#/components/responses/UpdateProjectResponse"},"400":{"$ref":"#/components/responses/BadRequestApiResponse"},"401":{"$ref":"#/components/responses/UnauthorizedApiResponse"},"403":{"$ref":"#/components/responses/ForbiddenApiResponse"},"404":{"$ref":"#/components/responses/ErrorApiResponse"},"429":{"$ref":"#/components/responses/TooManyRequestsApiResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorApiResponse"}},"summary":"Update a project","tags":["projects"]}}}} ``` ## Delete an existing project > Permanently deletes a project by ID.\ > \ > \*\*Rate limit:\*\* 120 requests per minute ```json {"openapi":"3.0.3","info":{"title":"Pylon API.","version":"1.0.0"},"tags":[],"servers":[{"description":"US region","url":"https://api.usepylon.com"},{"description":"EU region","url":"https://api.eu.usepylon.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"description":"Authorization: Bearer ","scheme":"bearer","type":"http"}},"responses":{"DeleteProjectResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteProjectResponseBody"}}},"description":""},"BadRequestApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request was invalid or could not be completed."},"UnauthorizedApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request could not be authenticated for this API."},"ForbiddenApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The authenticated caller or organization is not allowed to access this endpoint or operation."},"ErrorApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":""},"TooManyRequestsApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request exceeded the applicable rate limit.","headers":{"Retry-After":{"description":"Seconds until the next request to this endpoint is permitted.","schema":{"format":"int64","type":"integer"}},"X-Retry-After":{"description":"Seconds until the full per-minute allowance is restored. Capacity returns gradually before then.","schema":{"format":"int64","type":"integer"}}}},"InternalServerErrorApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"An unexpected internal error occurred."}},"schemas":{"DeleteProjectResponseBody":{"properties":{"request_id":{"description":"The request ID for tracking.","type":"string"}},"required":["request_id"],"type":"object"},"ErrorApiResponseBody":{"properties":{"code":{"description":"A stable machine-readable identifier for this failure, safe to branch on\ninstead of the message text. Omitted when the failure has no assigned code.\n\nKnown values: `recipients_suppressed`, `email_bounced`, `internal_issue_reply_not_allowed`, `duplicate_object`, `invalid_authorization_header`, `invalid_api_token`, `invalid_oauth_token`, `wrong_region_token`, `organization_deactivated`, `organization_suspended`, `permission_denied`, `oauth_not_permitted`, `rate_limited`, `not_found`, `method_not_allowed`, `payload_too_large`, `invalid_request_body`, `internal_error`, `invalid_webhook_credentials`, `organization_inactive`. This list is not exhaustive.","type":"string"},"errors":{"description":"The list of errors.","items":{"type":"string"},"type":"array"},"exists_id":{"description":"The ID of the object that already exists if this is a duplicate object error.","type":"string"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"required":["request_id"],"type":"object"}}},"paths":{"/projects/{id}":{"delete":{"description":"Permanently deletes a project by ID.\n\n**Rate limit:** 120 requests per minute","operationId":"DeleteProject","parameters":[{"description":"The ID of the project to delete.","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/DeleteProjectResponse"},"400":{"$ref":"#/components/responses/BadRequestApiResponse"},"401":{"$ref":"#/components/responses/UnauthorizedApiResponse"},"403":{"$ref":"#/components/responses/ForbiddenApiResponse"},"404":{"$ref":"#/components/responses/ErrorApiResponse"},"429":{"$ref":"#/components/responses/TooManyRequestsApiResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorApiResponse"}},"summary":"Delete an existing project","tags":["projects"]}}}} ``` ## Create a project > Creates a new project for an account. Provide a name or project\_template\_id. A template supplies defaults; non-empty name and description\_html values and supplied customer\_portal\_visible and owner\_id values override them. Supplying either start\_date or end\_date replaces both template dates.\ > \ > \*\*Rate limit:\*\* 300 requests per minute ```json {"openapi":"3.0.3","info":{"title":"Pylon API.","version":"1.0.0"},"tags":[],"servers":[{"description":"US region","url":"https://api.usepylon.com"},{"description":"EU region","url":"https://api.eu.usepylon.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"description":"Authorization: Bearer ","scheme":"bearer","type":"http"}},"schemas":{"CreateProjectRequestBody":{"properties":{"account_id":{"description":"Account ID for this project","type":"string"},"customer_portal_visible":{"default":false,"description":"Customer portal visible for this project","type":"boolean"},"description_html":{"description":"Description HTML for this project","type":"string"},"end_date":{"description":"End date for this project, in RFC 3339 format","format":"date-time","type":"string"},"name":{"description":"Name for this project. Required unless project_template_id is provided. When both are provided, this name overrides the template's name.","type":"string"},"owner_id":{"description":"Owner ID for this project","type":"string"},"project_template_id":{"description":"Project template ID for this project. When provided, it supplies defaults; non-empty name and description_html values and supplied customer_portal_visible and owner_id values override them. Supplying either start_date or end_date replaces both template dates.","type":"string"},"start_date":{"description":"Start date for this project, in RFC 3339 format","format":"date-time","type":"string"}},"required":["account_id"],"type":"object"},"CreateProjectResponseBody":{"properties":{"data":{"$ref":"#/components/schemas/Project"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"required":["data","request_id"],"type":"object"},"Project":{"properties":{"account":{"$ref":"#/components/schemas/MiniAccount"},"archived_at":{"description":"The archived at time of the project in RFC3339 format.","format":"date-time","type":"string"},"created_at":{"description":"The created at time of the project.","format":"date-time","type":"string"},"custom_fields":{"additionalProperties":{"$ref":"#/components/schemas/CustomFieldValue"},"description":"Custom fields for this project, keyed by slug.","nullable":true,"type":"object"},"customer_portal_visible":{"description":"The customer portal visible of the project.","type":"boolean"},"description_html":{"description":"The description of the project in HTML format.","type":"string"},"end_date":{"description":"The end date of the project in RFC3339 format.","format":"date-time","type":"string"},"id":{"description":"The ID of the project.","type":"string"},"is_archived":{"description":"Whether the project is archived.","type":"boolean"},"name":{"description":"The name of the project.","type":"string"},"owner_id":{"description":"The owner ID of the project.","type":"string"},"progress":{"description":"The fraction of completed tasks, from 0 to 1.","format":"double","type":"number"},"project_template":{"$ref":"#/components/schemas/MiniProjectTemplate"},"start_date":{"description":"The start date of the project in RFC3339 format.","format":"date-time","type":"string"},"status":{"description":"The status of the project. One of not_started, in_progress, or completed.\n\nKnown values: `not_started`, `in_progress`, `completed`. This list is not exhaustive.","type":"string"},"updated_at":{"description":"The updated at time of the project.","format":"date-time","type":"string"}},"required":["created_at","customer_portal_visible","id","is_archived","name","progress","status","updated_at"],"type":"object"},"MiniAccount":{"properties":{"external_ids":{"description":"External IDs associated with the account.","items":{"$ref":"#/components/schemas/ExternalID"},"nullable":true,"type":"array"},"id":{"description":"The ID of the account.","type":"string"}},"required":["id"],"type":"object"},"ExternalID":{"properties":{"external_id":{"description":"The external ID. Must be unique per object type (ex. account).","type":"string"},"label":{"description":"The label of the external ID. Must be unique per object.","type":"string"}},"type":"object"},"CustomFieldValue":{"description":"A custom field value to set. Custom fields not listed in a write request are left unchanged.","properties":{"slug":{"description":"The slug of the custom field.","type":"string"},"value":{"description":"The value of the custom field. Only to be used for single-valued custom fields. If unset, the custom field will be unset. If the custom field is a select field, the value must be the select option slug, which you can find from the GET /custom-fields endpoint. If the custom field is a relationship field, the value must be the related object ID.","type":"string"},"values":{"description":"The values of the custom field. Only to be used for multi-valued custom fields (ex. multiselect). Replaces the full selection; it does not add to or remove from the existing values. If unset, the custom field will be unset. If the custom field is a multiselect field, the values must be the select option slugs which you can find from the GET /custom-fields endpoint.","items":{"type":"string"},"type":"array"}},"title":"CustomFieldValue","type":"object"},"MiniProjectTemplate":{"properties":{"id":{"description":"The ID of the project template.","type":"string"}},"required":["id"],"type":"object"},"ErrorApiResponseBody":{"properties":{"code":{"description":"A stable machine-readable identifier for this failure, safe to branch on\ninstead of the message text. Omitted when the failure has no assigned code.\n\nKnown values: `recipients_suppressed`, `email_bounced`, `internal_issue_reply_not_allowed`, `duplicate_object`, `invalid_authorization_header`, `invalid_api_token`, `invalid_oauth_token`, `wrong_region_token`, `organization_deactivated`, `organization_suspended`, `permission_denied`, `oauth_not_permitted`, `rate_limited`, `not_found`, `method_not_allowed`, `payload_too_large`, `invalid_request_body`, `internal_error`, `invalid_webhook_credentials`, `organization_inactive`. This list is not exhaustive.","type":"string"},"errors":{"description":"The list of errors.","items":{"type":"string"},"type":"array"},"exists_id":{"description":"The ID of the object that already exists if this is a duplicate object error.","type":"string"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"required":["request_id"],"type":"object"}},"responses":{"CreateProjectResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProjectResponseBody"}}},"description":""},"BadRequestApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request was invalid or could not be completed."},"UnauthorizedApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request could not be authenticated for this API."},"ForbiddenApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The authenticated caller or organization is not allowed to access this endpoint or operation."},"ErrorApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":""},"TooManyRequestsApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request exceeded the applicable rate limit.","headers":{"Retry-After":{"description":"Seconds until the next request to this endpoint is permitted.","schema":{"format":"int64","type":"integer"}},"X-Retry-After":{"description":"Seconds until the full per-minute allowance is restored. Capacity returns gradually before then.","schema":{"format":"int64","type":"integer"}}}},"InternalServerErrorApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"An unexpected internal error occurred."}}},"paths":{"/projects":{"post":{"description":"Creates a new project for an account. Provide a name or project_template_id. A template supplies defaults; non-empty name and description_html values and supplied customer_portal_visible and owner_id values override them. Supplying either start_date or end_date replaces both template dates.\n\n**Rate limit:** 300 requests per minute","operationId":"CreateProject","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProjectRequestBody"}}}},"responses":{"200":{"$ref":"#/components/responses/CreateProjectResponse"},"400":{"$ref":"#/components/responses/BadRequestApiResponse"},"401":{"$ref":"#/components/responses/UnauthorizedApiResponse"},"403":{"$ref":"#/components/responses/ForbiddenApiResponse"},"404":{"$ref":"#/components/responses/ErrorApiResponse"},"429":{"$ref":"#/components/responses/TooManyRequestsApiResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorApiResponse"}},"summary":"Create a project","tags":["projects"]}}}} ``` ## Get a milestone by its ID > Returns a single milestone by ID.\ > \ > \*\*Rate limit:\*\* 300 requests per minute ```json {"openapi":"3.0.3","info":{"title":"Pylon API.","version":"1.0.0"},"tags":[],"servers":[{"description":"US region","url":"https://api.usepylon.com"},{"description":"EU region","url":"https://api.eu.usepylon.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"description":"Authorization: Bearer ","scheme":"bearer","type":"http"}},"responses":{"GetMilestoneResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetMilestoneResponseBody"}}},"description":""},"BadRequestApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request was invalid or could not be completed."},"UnauthorizedApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request could not be authenticated for this API."},"ForbiddenApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The authenticated caller or organization is not allowed to access this endpoint or operation."},"ErrorApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":""},"TooManyRequestsApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request exceeded the applicable rate limit.","headers":{"Retry-After":{"description":"Seconds until the next request to this endpoint is permitted.","schema":{"format":"int64","type":"integer"}},"X-Retry-After":{"description":"Seconds until the full per-minute allowance is restored. Capacity returns gradually before then.","schema":{"format":"int64","type":"integer"}}}},"InternalServerErrorApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"An unexpected internal error occurred."}},"schemas":{"GetMilestoneResponseBody":{"properties":{"data":{"$ref":"#/components/schemas/Milestone"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"required":["data","request_id"],"type":"object"},"Milestone":{"properties":{"account":{"$ref":"#/components/schemas/MiniAccount"},"created_at":{"format":"date-time","type":"string"},"due_date":{"format":"date-time","type":"string"},"id":{"type":"string"},"name":{"type":"string"},"project":{"$ref":"#/components/schemas/MiniProject"},"updated_at":{"format":"date-time","type":"string"}},"required":["created_at","id","name","updated_at"],"type":"object"},"MiniAccount":{"properties":{"external_ids":{"description":"External IDs associated with the account.","items":{"$ref":"#/components/schemas/ExternalID"},"nullable":true,"type":"array"},"id":{"description":"The ID of the account.","type":"string"}},"required":["id"],"type":"object"},"ExternalID":{"properties":{"external_id":{"description":"The external ID. Must be unique per object type (ex. account).","type":"string"},"label":{"description":"The label of the external ID. Must be unique per object.","type":"string"}},"type":"object"},"MiniProject":{"properties":{"id":{"description":"The ID of the project.","type":"string"}},"required":["id"],"type":"object"},"ErrorApiResponseBody":{"properties":{"code":{"description":"A stable machine-readable identifier for this failure, safe to branch on\ninstead of the message text. Omitted when the failure has no assigned code.\n\nKnown values: `recipients_suppressed`, `email_bounced`, `internal_issue_reply_not_allowed`, `duplicate_object`, `invalid_authorization_header`, `invalid_api_token`, `invalid_oauth_token`, `wrong_region_token`, `organization_deactivated`, `organization_suspended`, `permission_denied`, `oauth_not_permitted`, `rate_limited`, `not_found`, `method_not_allowed`, `payload_too_large`, `invalid_request_body`, `internal_error`, `invalid_webhook_credentials`, `organization_inactive`. This list is not exhaustive.","type":"string"},"errors":{"description":"The list of errors.","items":{"type":"string"},"type":"array"},"exists_id":{"description":"The ID of the object that already exists if this is a duplicate object error.","type":"string"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"required":["request_id"],"type":"object"}}},"paths":{"/milestones/{id}":{"get":{"description":"Returns a single milestone by ID.\n\n**Rate limit:** 300 requests per minute","operationId":"GetMilestone","parameters":[{"description":"The ID of the milestone to fetch.","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/GetMilestoneResponse"},"400":{"$ref":"#/components/responses/BadRequestApiResponse"},"401":{"$ref":"#/components/responses/UnauthorizedApiResponse"},"403":{"$ref":"#/components/responses/ForbiddenApiResponse"},"404":{"$ref":"#/components/responses/ErrorApiResponse"},"429":{"$ref":"#/components/responses/TooManyRequestsApiResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorApiResponse"}},"summary":"Get a milestone by its ID","tags":["milestones"]}}}} ``` ## Update a milestone > Updates an existing milestone. Only provided fields are modified.\ > \ > \*\*Rate limit:\*\* 300 requests per minute ```json {"openapi":"3.0.3","info":{"title":"Pylon API.","version":"1.0.0"},"tags":[],"servers":[{"description":"US region","url":"https://api.usepylon.com"},{"description":"EU region","url":"https://api.eu.usepylon.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"description":"Authorization: Bearer ","scheme":"bearer","type":"http"}},"schemas":{"UpdateMilestoneRequestBody":{"properties":{"due_date":{"description":"Due date for this milestone, in RFC 3339 format. Set to an empty string to clear it.","type":"string"},"name":{"description":"Name for this milestone","type":"string"}},"type":"object"},"UpdateMilestoneResponseBody":{"properties":{"data":{"$ref":"#/components/schemas/Milestone"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"required":["data","request_id"],"type":"object"},"Milestone":{"properties":{"account":{"$ref":"#/components/schemas/MiniAccount"},"created_at":{"format":"date-time","type":"string"},"due_date":{"format":"date-time","type":"string"},"id":{"type":"string"},"name":{"type":"string"},"project":{"$ref":"#/components/schemas/MiniProject"},"updated_at":{"format":"date-time","type":"string"}},"required":["created_at","id","name","updated_at"],"type":"object"},"MiniAccount":{"properties":{"external_ids":{"description":"External IDs associated with the account.","items":{"$ref":"#/components/schemas/ExternalID"},"nullable":true,"type":"array"},"id":{"description":"The ID of the account.","type":"string"}},"required":["id"],"type":"object"},"ExternalID":{"properties":{"external_id":{"description":"The external ID. Must be unique per object type (ex. account).","type":"string"},"label":{"description":"The label of the external ID. Must be unique per object.","type":"string"}},"type":"object"},"MiniProject":{"properties":{"id":{"description":"The ID of the project.","type":"string"}},"required":["id"],"type":"object"},"ErrorApiResponseBody":{"properties":{"code":{"description":"A stable machine-readable identifier for this failure, safe to branch on\ninstead of the message text. Omitted when the failure has no assigned code.\n\nKnown values: `recipients_suppressed`, `email_bounced`, `internal_issue_reply_not_allowed`, `duplicate_object`, `invalid_authorization_header`, `invalid_api_token`, `invalid_oauth_token`, `wrong_region_token`, `organization_deactivated`, `organization_suspended`, `permission_denied`, `oauth_not_permitted`, `rate_limited`, `not_found`, `method_not_allowed`, `payload_too_large`, `invalid_request_body`, `internal_error`, `invalid_webhook_credentials`, `organization_inactive`. This list is not exhaustive.","type":"string"},"errors":{"description":"The list of errors.","items":{"type":"string"},"type":"array"},"exists_id":{"description":"The ID of the object that already exists if this is a duplicate object error.","type":"string"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"required":["request_id"],"type":"object"}},"responses":{"UpdateMilestoneResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateMilestoneResponseBody"}}},"description":""},"BadRequestApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request was invalid or could not be completed."},"UnauthorizedApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request could not be authenticated for this API."},"ForbiddenApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The authenticated caller or organization is not allowed to access this endpoint or operation."},"ErrorApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":""},"TooManyRequestsApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request exceeded the applicable rate limit.","headers":{"Retry-After":{"description":"Seconds until the next request to this endpoint is permitted.","schema":{"format":"int64","type":"integer"}},"X-Retry-After":{"description":"Seconds until the full per-minute allowance is restored. Capacity returns gradually before then.","schema":{"format":"int64","type":"integer"}}}},"InternalServerErrorApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"An unexpected internal error occurred."}}},"paths":{"/milestones/{id}":{"patch":{"description":"Updates an existing milestone. Only provided fields are modified.\n\n**Rate limit:** 300 requests per minute","operationId":"UpdateMilestone","parameters":[{"description":"The ID of the milestone to update.","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateMilestoneRequestBody"}}}},"responses":{"200":{"$ref":"#/components/responses/UpdateMilestoneResponse"},"400":{"$ref":"#/components/responses/BadRequestApiResponse"},"401":{"$ref":"#/components/responses/UnauthorizedApiResponse"},"403":{"$ref":"#/components/responses/ForbiddenApiResponse"},"404":{"$ref":"#/components/responses/ErrorApiResponse"},"429":{"$ref":"#/components/responses/TooManyRequestsApiResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorApiResponse"}},"summary":"Update a milestone","tags":["milestones"]}}}} ``` ## Create a milestone > Creates a new milestone within a project.\ > \ > \*\*Rate limit:\*\* 300 requests per minute ```json {"openapi":"3.0.3","info":{"title":"Pylon API.","version":"1.0.0"},"tags":[],"servers":[{"description":"US region","url":"https://api.usepylon.com"},{"description":"EU region","url":"https://api.eu.usepylon.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"description":"Authorization: Bearer ","scheme":"bearer","type":"http"}},"schemas":{"CreateMilestoneRequestBody":{"properties":{"account_id":{"description":"Account ID for this project","type":"string"},"due_date":{"description":"Due date for this milestone, in RFC 3339 format","format":"date-time","type":"string"},"name":{"description":"Name for this milestone","type":"string"},"project_id":{"description":"Project ID for this milestone","type":"string"}},"required":["name","project_id"],"type":"object"},"CreateMilestoneResponseBody":{"properties":{"data":{"$ref":"#/components/schemas/Milestone"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"required":["data","request_id"],"type":"object"},"Milestone":{"properties":{"account":{"$ref":"#/components/schemas/MiniAccount"},"created_at":{"format":"date-time","type":"string"},"due_date":{"format":"date-time","type":"string"},"id":{"type":"string"},"name":{"type":"string"},"project":{"$ref":"#/components/schemas/MiniProject"},"updated_at":{"format":"date-time","type":"string"}},"required":["created_at","id","name","updated_at"],"type":"object"},"MiniAccount":{"properties":{"external_ids":{"description":"External IDs associated with the account.","items":{"$ref":"#/components/schemas/ExternalID"},"nullable":true,"type":"array"},"id":{"description":"The ID of the account.","type":"string"}},"required":["id"],"type":"object"},"ExternalID":{"properties":{"external_id":{"description":"The external ID. Must be unique per object type (ex. account).","type":"string"},"label":{"description":"The label of the external ID. Must be unique per object.","type":"string"}},"type":"object"},"MiniProject":{"properties":{"id":{"description":"The ID of the project.","type":"string"}},"required":["id"],"type":"object"},"ErrorApiResponseBody":{"properties":{"code":{"description":"A stable machine-readable identifier for this failure, safe to branch on\ninstead of the message text. Omitted when the failure has no assigned code.\n\nKnown values: `recipients_suppressed`, `email_bounced`, `internal_issue_reply_not_allowed`, `duplicate_object`, `invalid_authorization_header`, `invalid_api_token`, `invalid_oauth_token`, `wrong_region_token`, `organization_deactivated`, `organization_suspended`, `permission_denied`, `oauth_not_permitted`, `rate_limited`, `not_found`, `method_not_allowed`, `payload_too_large`, `invalid_request_body`, `internal_error`, `invalid_webhook_credentials`, `organization_inactive`. This list is not exhaustive.","type":"string"},"errors":{"description":"The list of errors.","items":{"type":"string"},"type":"array"},"exists_id":{"description":"The ID of the object that already exists if this is a duplicate object error.","type":"string"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"required":["request_id"],"type":"object"}},"responses":{"CreateMilestoneResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMilestoneResponseBody"}}},"description":""},"BadRequestApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request was invalid or could not be completed."},"UnauthorizedApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request could not be authenticated for this API."},"ForbiddenApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The authenticated caller or organization is not allowed to access this endpoint or operation."},"ErrorApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":""},"TooManyRequestsApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request exceeded the applicable rate limit.","headers":{"Retry-After":{"description":"Seconds until the next request to this endpoint is permitted.","schema":{"format":"int64","type":"integer"}},"X-Retry-After":{"description":"Seconds until the full per-minute allowance is restored. Capacity returns gradually before then.","schema":{"format":"int64","type":"integer"}}}},"InternalServerErrorApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"An unexpected internal error occurred."}}},"paths":{"/milestones":{"post":{"description":"Creates a new milestone within a project.\n\n**Rate limit:** 300 requests per minute","operationId":"CreateMilestone","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMilestoneRequestBody"}}}},"responses":{"200":{"$ref":"#/components/responses/CreateMilestoneResponse"},"400":{"$ref":"#/components/responses/BadRequestApiResponse"},"401":{"$ref":"#/components/responses/UnauthorizedApiResponse"},"403":{"$ref":"#/components/responses/ForbiddenApiResponse"},"404":{"$ref":"#/components/responses/ErrorApiResponse"},"429":{"$ref":"#/components/responses/TooManyRequestsApiResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorApiResponse"}},"summary":"Create a milestone","tags":["milestones"]}}}} ``` ## Delete a milestone > Permanently deletes a milestone by ID.\ > \ > \*\*Rate limit:\*\* 300 requests per minute ```json {"openapi":"3.0.3","info":{"title":"Pylon API.","version":"1.0.0"},"tags":[],"servers":[{"description":"US region","url":"https://api.usepylon.com"},{"description":"EU region","url":"https://api.eu.usepylon.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"description":"Authorization: Bearer ","scheme":"bearer","type":"http"}},"responses":{"DeleteMilestoneResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteMilestoneResponseBody"}}},"description":""},"BadRequestApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request was invalid or could not be completed."},"UnauthorizedApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request could not be authenticated for this API."},"ForbiddenApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The authenticated caller or organization is not allowed to access this endpoint or operation."},"ErrorApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":""},"TooManyRequestsApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request exceeded the applicable rate limit.","headers":{"Retry-After":{"description":"Seconds until the next request to this endpoint is permitted.","schema":{"format":"int64","type":"integer"}},"X-Retry-After":{"description":"Seconds until the full per-minute allowance is restored. Capacity returns gradually before then.","schema":{"format":"int64","type":"integer"}}}},"InternalServerErrorApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"An unexpected internal error occurred."}},"schemas":{"DeleteMilestoneResponseBody":{"properties":{"request_id":{"description":"The request ID for tracking.","type":"string"}},"required":["request_id"],"type":"object"},"ErrorApiResponseBody":{"properties":{"code":{"description":"A stable machine-readable identifier for this failure, safe to branch on\ninstead of the message text. Omitted when the failure has no assigned code.\n\nKnown values: `recipients_suppressed`, `email_bounced`, `internal_issue_reply_not_allowed`, `duplicate_object`, `invalid_authorization_header`, `invalid_api_token`, `invalid_oauth_token`, `wrong_region_token`, `organization_deactivated`, `organization_suspended`, `permission_denied`, `oauth_not_permitted`, `rate_limited`, `not_found`, `method_not_allowed`, `payload_too_large`, `invalid_request_body`, `internal_error`, `invalid_webhook_credentials`, `organization_inactive`. This list is not exhaustive.","type":"string"},"errors":{"description":"The list of errors.","items":{"type":"string"},"type":"array"},"exists_id":{"description":"The ID of the object that already exists if this is a duplicate object error.","type":"string"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"required":["request_id"],"type":"object"}}},"paths":{"/milestones/{id}":{"delete":{"description":"Permanently deletes a milestone by ID.\n\n**Rate limit:** 300 requests per minute","operationId":"DeleteMilestone","parameters":[{"description":"The ID of the milestone to delete.","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/DeleteMilestoneResponse"},"400":{"$ref":"#/components/responses/BadRequestApiResponse"},"401":{"$ref":"#/components/responses/UnauthorizedApiResponse"},"403":{"$ref":"#/components/responses/ForbiddenApiResponse"},"404":{"$ref":"#/components/responses/ErrorApiResponse"},"429":{"$ref":"#/components/responses/TooManyRequestsApiResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorApiResponse"}},"summary":"Delete a milestone","tags":["milestones"]}}}} ``` ## Search for milestones by a given filter > Filterable fields and their allowed operators:\ > \ > Field | Allowed operators |\ > \--- | --- |\ > \`project\_id\` | \`equals\`, \`in\`, \`not\_in\` |\ > \`account\_id\` | \`equals\`, \`in\`, \`not\_in\`, \`is\_set\`, \`is\_unset\` |\ > \`due\_date\` | \`time\_is\_after\`, \`time\_is\_before\`, \`time\_range\`, \`is\_set\`, \`is\_unset\` |\ > \`created\_at\` | \`time\_is\_after\`, \`time\_is\_before\`, \`time\_range\` |\ > \`updated\_at\` | \`time\_is\_after\`, \`time\_is\_before\`, \`time\_range\` |\ > \`started\_at\` | \`time\_is\_after\`, \`time\_is\_before\`, \`time\_range\`, \`is\_set\` |\ > \`completed\_at\` | \`time\_is\_after\`, \`time\_is\_before\`, \`time\_range\`, \`is\_set\` |\ > \ > Timestamp values use RFC3339 format. Milestones belonging to an unlaunched project are not returned.\ > \ > \*\*Rate limit:\*\* 120 requests per minute ```json {"openapi":"3.0.3","info":{"title":"Pylon API.","version":"1.0.0"},"tags":[],"servers":[{"description":"US region","url":"https://api.usepylon.com"},{"description":"EU region","url":"https://api.eu.usepylon.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"description":"Authorization: Bearer ","scheme":"bearer","type":"http"}},"schemas":{"SearchMilestonesRequest":{"properties":{"cursor":{"description":"The cursor to use for pagination.","type":"string"},"filter":{"$ref":"#/components/schemas/Filter"},"limit":{"description":"The number of milestones to fetch. Defaults to 100. Must be between 1 and 1000.","format":"int64","type":"integer"}},"type":"object"},"Filter":{"properties":{"field":{"description":"The field for this filter. For allowed fields, see the documentation for\nthe specific endpoint you are using.\nFor non-compound filters (any operators other than \"and\" or \"or\"),\nfield must be set, along with either value or values, depending on the operator.","type":"string"},"operator":{"description":"The operator for this filter.","enum":["equals","not_equals","contains","does_not_contain","in","not_in","and","or","time_is_after","time_is_before","time_range","string_contains","string_does_not_contain","is_set","is_unset","greater_than","less_than","greater_than_or_equals","less_than_or_equals","includes_all_of","starts_with","ends_with"],"type":"string"},"subfilters":{"description":"Sub-filters for this filter. Valid only when operator is \"and\" or \"or\".\nThe maximum allowed depth for a tree of filters is 3, counting the top-level filter.","items":{"$ref":"#/components/schemas/Filter"},"type":"array"},"value":{"description":"The value for this filter. Used by single-valued operators: \"equals\", \"not_equals\",\n\"contains\", \"does_not_contain\", \"string_contains\", \"string_does_not_contain\",\n\"starts_with\", \"ends_with\", \"time_is_after\", \"time_is_before\", \"greater_than\",\n\"less_than\", \"greater_than_or_equals\", and \"less_than_or_equals\".","type":"string"},"values":{"description":"The values for this filter. Used by multi-valued operators: \"in\", \"not_in\", and\n\"includes_all_of\". For \"time_range\", set to [start, end].","items":{"type":"string"},"type":"array"}},"required":["operator"],"type":"object"},"SearchMilestonesResponseBody":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Milestone"},"type":"array"},"pagination":{"$ref":"#/components/schemas/Pagination"},"request_id":{"type":"string"}},"required":["data","request_id"],"type":"object"},"Milestone":{"properties":{"account":{"$ref":"#/components/schemas/MiniAccount"},"created_at":{"format":"date-time","type":"string"},"due_date":{"format":"date-time","type":"string"},"id":{"type":"string"},"name":{"type":"string"},"project":{"$ref":"#/components/schemas/MiniProject"},"updated_at":{"format":"date-time","type":"string"}},"required":["created_at","id","name","updated_at"],"type":"object"},"MiniAccount":{"properties":{"external_ids":{"description":"External IDs associated with the account.","items":{"$ref":"#/components/schemas/ExternalID"},"nullable":true,"type":"array"},"id":{"description":"The ID of the account.","type":"string"}},"required":["id"],"type":"object"},"ExternalID":{"properties":{"external_id":{"description":"The external ID. Must be unique per object type (ex. account).","type":"string"},"label":{"description":"The label of the external ID. Must be unique per object.","type":"string"}},"type":"object"},"MiniProject":{"properties":{"id":{"description":"The ID of the project.","type":"string"}},"required":["id"],"type":"object"},"Pagination":{"description":"Pagination information for list responses. Absent when there are no more results.","properties":{"cursor":{"description":"The cursor for the next page of results.","type":"string"},"has_next_page":{"description":"Indicates if there is a next page of results.","type":"boolean"}},"required":["cursor","has_next_page"],"title":"Pagination","type":"object"},"ErrorApiResponseBody":{"properties":{"code":{"description":"A stable machine-readable identifier for this failure, safe to branch on\ninstead of the message text. Omitted when the failure has no assigned code.\n\nKnown values: `recipients_suppressed`, `email_bounced`, `internal_issue_reply_not_allowed`, `duplicate_object`, `invalid_authorization_header`, `invalid_api_token`, `invalid_oauth_token`, `wrong_region_token`, `organization_deactivated`, `organization_suspended`, `permission_denied`, `oauth_not_permitted`, `rate_limited`, `not_found`, `method_not_allowed`, `payload_too_large`, `invalid_request_body`, `internal_error`, `invalid_webhook_credentials`, `organization_inactive`. This list is not exhaustive.","type":"string"},"errors":{"description":"The list of errors.","items":{"type":"string"},"type":"array"},"exists_id":{"description":"The ID of the object that already exists if this is a duplicate object error.","type":"string"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"required":["request_id"],"type":"object"}},"responses":{"SearchMilestonesResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchMilestonesResponseBody"}}},"description":""},"BadRequestApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request was invalid or could not be completed."},"UnauthorizedApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request could not be authenticated for this API."},"ForbiddenApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The authenticated caller or organization is not allowed to access this endpoint or operation."},"TooManyRequestsApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request exceeded the applicable rate limit.","headers":{"Retry-After":{"description":"Seconds until the next request to this endpoint is permitted.","schema":{"format":"int64","type":"integer"}},"X-Retry-After":{"description":"Seconds until the full per-minute allowance is restored. Capacity returns gradually before then.","schema":{"format":"int64","type":"integer"}}}},"InternalServerErrorApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"An unexpected internal error occurred."}}},"paths":{"/milestones/search":{"post":{"description":"Filterable fields and their allowed operators:\n\n Field | Allowed operators |\n --- | --- |\n `project_id` | `equals`, `in`, `not_in` |\n `account_id` | `equals`, `in`, `not_in`, `is_set`, `is_unset` |\n `due_date` | `time_is_after`, `time_is_before`, `time_range`, `is_set`, `is_unset` |\n `created_at` | `time_is_after`, `time_is_before`, `time_range` |\n `updated_at` | `time_is_after`, `time_is_before`, `time_range` |\n `started_at` | `time_is_after`, `time_is_before`, `time_range`, `is_set` |\n `completed_at` | `time_is_after`, `time_is_before`, `time_range`, `is_set` |\n\nTimestamp values use RFC3339 format. Milestones belonging to an unlaunched project are not returned.\n\n**Rate limit:** 120 requests per minute","operationId":"SearchMilestones","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchMilestonesRequest"}}}},"responses":{"200":{"$ref":"#/components/responses/SearchMilestonesResponse"},"400":{"$ref":"#/components/responses/BadRequestApiResponse"},"401":{"$ref":"#/components/responses/UnauthorizedApiResponse"},"403":{"$ref":"#/components/responses/ForbiddenApiResponse"},"429":{"$ref":"#/components/responses/TooManyRequestsApiResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorApiResponse"}},"summary":"Search for milestones by a given filter","tags":["milestones"]}}}} ``` --- # 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/api-reference/tasks-and-projects.md?ask=&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.