swagger: '2.0'
info:
title: PlanRadar's API Documentation Approval Requests V2 Tickets API
version: '2.0'
description: "Welcome to PlanRadar's API documentation, here you can find all the details about our APIs as well as test them online.<br />\n <h5>Rate Limits</h5>30 requests per minute per account, aggregated across all tokens.<br />\n If the threshold is exceeded, a 5-minute cooldown is applied to the account, aggregated across all tokens.<br />\n During the cooldown period, further requests may be rejected until the cooldown ends.<br />\n In rare cases, an endpoint may have a different rate limit than the default. When that happens, the differing limit will be explicitly stated in the API documentation for that endpoint.<br />\n <h5>Access Key</h5>In order to be able to access any API you have to create an access token.Therefore you have to follow these steps:-\n <ul>\n <li>Go to your profile page and click on Personal Access Tokens on the left side bar</li><li>Click on the 'Create Access Token' top right button in order to create a new access token.</li><li>Copy the created token and paste it into the field that pops up when you click on the 'Authorize' button </li><li>Note: you can copy the token only once.</li><li>Now you can easily access any API</li>\n </ul>\n <h5>V2 APIs</h5>We are currently working on upgrading all our APIs to v2, and we recommend that you use v2 APIs if it is available.\n <p>V2 APIs are faster, robust and more flexible than v1 APIs</p>"
basePath: /
schemes:
- https
- http
consumes:
- application/json
produces:
- application/json
tags:
- name: Tickets
description: All operations on PlanRadar tickets
paths:
/api/v1/{customer_id}/projects/{project_id}/tickets/load:
get:
summary: Retrieves All tickets
tags:
- Tickets
produces:
- application/json
description: "Load all tickets from a specific project <br />\n Without any extra parameters it will return the first 100 tickets ordered by ID ascending. Extra parameters can be added to filter and sort the results.<br />\n <b>Ticket Sorting:</b>\n Field name to sort the results based on it, sort is always ascending unless the field name is prefixed with a minus (U+002D HYPHEN-MINUS, “-“) i.e. `-id` or `id`\n <br /><b>Example: </b> `tickets/load?sort=-component_id`<br />\n <b>Ticket Filtring:</b>\n You can use a saved filter by providing its id to the `apply_filter` parameter. Also, you can use the on-fly filters.<br />\n <b>On-Fly Filters</b>\n You can filter tickets based on the value of any of its attributes<br />\n <b>Example #1:</b> All tickets where status is open\n `tickets/load?filter[status_id]=1`<br/>\n <b>Example #2:</b> All tickets where status is open, and priority is high\n `tickets/load?filter[status_id]=1&filter[prority_id]=3`\n <br />\n <b>Status Dictionary:</b> [1 (lm)= Open, 2 (ol) = In-Progress, 3 (ma) = Resolved, 4 (ex) = Feedback, 5 (gk) = Closed, 6 (ky) = Rejected]\n <b>Priority Dictionary:</b> [1 = Low, 2 = Normal, 3 = High]\n "
security:
- apiKey: []
parameters:
- name: customer_id
in: path
type: string
required: true
- name: project_id
in: path
type: string
required: true
description: Set project_id to `0` if you want to load tickets from all projects
- name: page
in: query
type: integer
- name: pagesize
in: query
type: integer
description: Maximum is 500, default is 100
- name: last_sync_date
in: query
type: string
- name: sort
in: query
type: string
- name: filter
in: query
type: string
- name: apply_filter
in: query
type: string
- name: search
in: query
type: string
description: Search keyword to filter tickets based on it
responses:
'406':
description: unsupported accept header
/api/v1/{customer_id}/projects/{project_id}/tickets/multi_update:
put:
summary: Multi Update Tickets based on the provided filteration, no filter will update all data for the project id
tags:
- Tickets
description: Multi update tickets, for typed values it has to be grouped by the ticket type, all any other fields should be added in the attributes, the key is the field name, the value is the new value, filter data is OPTIONAL and can be used in either the query string or in the body of the request or both
x-websocket-response:
channel: user_{customerId}_{userId}
message_type: cable-events
payload:
type: object
properties:
multiupdate-progress:
type: integer
description: Always 1, signals completion
failed-count:
type: integer
description: Number of tickets that failed to update
produces:
- application/json
parameters:
- name: customer_id
in: path
type: string
required: true
- name: project_id
in: path
type: string
required: true
- name: filter
in: query
type: string
description: 'Used to filter tickets based on any conditions of the related model, filter[author_id]=1 will list all tickets related to this author id, similar to filter[author.id]=1, the second one will use the condition based on the user table such a filter is available filter[author.email]=test@email.com, for multiple values for the same filter use filter[id][]=PN&filter[id][]=nE,,,, available models are: customer, ticket_type, project, component, status, ticket, author, assigned_to, updated_by, due_by, overdue_by, creation_period'
- name: apply_filter
in: query
type: string
description: ID of the custom filter to be applied before returning the data
- name: batch_update_object
in: body
schema:
type: object
properties:
data:
type: object
properties:
attributes:
type: object
properties:
field-name:
type: string
ticket_type_id:
type: object
properties:
typed-field-id:
type: string
filter:
type: object
properties:
uuid:
type: array
items:
type: string
component_id:
type: string
required:
- title
- content
responses:
'406':
description: unsupported accept header
/api/v1/{customer_id}/projects/{project_id}/tickets/{uuid}:
get:
summary: Show one ticket based on its UUID
tags:
- Tickets
produces:
- application/json
parameters:
- name: customer_id
in: path
type: string
required: true
- name: project_id
in: path
type: string
required: true
- name: uuid
in: path
type: string
required: true
responses:
'404':
description: Ticket Not found
put:
summary: Update one ticket
tags:
- Tickets
produces:
- application/json
security:
- apiKey: []
parameters:
- name: customer_id
in: path
type: string
required: true
- name: project_id
in: path
type: string
required: true
- name: uuid
in: path
type: string
description: UUID of the ticket to load
required: true
- name: clean_up_assets
in: query
type: boolean
description: If set to true, it will remove any assets that dont belong to the ticket
required: false
- name: ticket
in: body
schema:
type: object
properties:
data:
type: object
properties:
attributes:
$ref: '#/definitions/Ticket'
required:
- title
- content
responses:
'404':
description: Ticket Not found
delete:
summary: Delete one ticket
tags:
- Tickets
produces:
- application/json
security:
- apiKey: []
parameters:
- name: customer_id
in: path
type: string
required: true
- name: project_id
in: path
type: string
required: true
- name: uuid
in: path
type: string
description: UUID of the ticket to delete
required: true
responses:
'404':
description: Ticket Not found
/api/v1/{customer_id}/projects/{project_id}/tickets/:
get:
summary: Retrieves All tickets
tags:
- Tickets
description: "This API is similar to `tickets/load` API the only difference that it retrieves all children ticket in the same page.\n Requesting this API with pagesize = 10 will return the first matched 10 tickets plus all their children tickets.<br />\n Without any extra parameters it will return the first 100 tickets ordered by ID ascending. Extra parameters can be added to filter and sort the results.<br />\n <b>Ticket Sorting:</b>\n Field name to sort the results based on it, sort is always ascending unless the field name is prefixed with a minus (U+002D HYPHEN-MINUS, “-“) i.e. `-id` or `id`\n <br /><b>Example: </b> `tickets/load?sort=-component_id`<br />\n <b>Ticket Filtring:</b>\n You can use a saved filter by providing its id to the `apply_filter` parameter. Also, you can use the on-fly filters.<br />\n <b>On-Fly Filters</b>\n You can filter tickets based on the value of any of its attributes<br />\n <b>Example #1:</b> All tickets where status is open\n `tickets/load?filter[status_id]=1`<br/>\n <b>Example #2:</b> All tickets where status is open, and priority is high\n `tickets/load?filter[status_id]=1&filter[prority_id]=3`\n <br />\n <b>Status Dictionary:</b> [1 (lm)= Open, 2 (ol) = In-Progress, 3 (ma) = Resolved, 4 (ex) = Feedback, 5 (gk) = Closed, 6 (ky) = Rejected]\n <b>Priority Dictionary:</b> [1 = Low, 2 = Normal, 3 = High]\n "
security:
- apiKey: []
produces:
- application/json
parameters:
- name: customer_id
in: path
type: string
required: true
- name: project_id
in: path
type: string
description: Set project_id to `0` if you want to load tickets from all projects
required: true
- name: page
in: query
type: integer
- name: pagesize
in: query
type: integer
description: Maximum is 500, default is 100
- name: last_sync_date
in: query
type: string
- name: sort
in: query
type: string
- name: filter
in: query
type: string
- name: apply_filter
in: query
type: string
- name: search
in: query
type: string
description: Search keyword to filter tickets based on it
responses:
'404':
description: Not Found
post:
summary: Create one ticket
tags:
- Tickets
produces:
- application/json
security:
- apiKey: []
parameters:
- name: customer_id
in: path
type: string
required: true
- name: project_id
in: path
type: string
required: true
- name: ticket
in: body
schema:
type: object
properties:
data:
type: object
properties:
attributes:
$ref: '#/definitions/Ticket'
responses:
'404':
description: Ticket Not found
/api/v1/{customer_id}/projects/{project_id}/tickets/{uuid}/comment:
post:
summary: Add a comment to a Ticket
tags:
- Tickets
produces:
- application/json
description: Add a comment to a specific ticket.
security:
- apiKey: []
parameters:
- name: customer_id
in: path
type: string
required: true
- name: project_id
in: path
type: string
required: true
- name: uuid
in: path
type: string
description: UUID of the ticket to add a comment to it
required: true
- name: comment
in: body
schema:
type: object
properties:
data:
type: object
properties:
attributes:
type: object
properties:
comment:
type: string
example: Hello World!
created_on:
type: string
description: 'Optional: leave blank and the current time will be used'
required:
- title
- content
responses:
'404':
description: Ticket Not found
/api/v1/{customer_id}/projects/{project_id}/tickets/{uuid}/export:
post:
summary: Export single ticket as PDF
tags:
- Tickets
produces:
- application/json
description: "Export single ticket as a PDF documnet\n If images included in the ticket more than 10, the ticket will be exported in a job.\n <br />\n <b>timezone_offset</b><br />\n Is used to convert all dates included in the PDF document to the correct timezone. the value should be the difference in minutes between UTC and your location."
security:
- apiKey: []
parameters:
- name: customer_id
in: path
type: string
required: true
- name: project_id
in: path
type: string
required: true
- name: uuid
in: path
type: string
description: UUID of the ticket to export
required: true
- name: template_id
in: query
type: string
description: ID of the template to be used for the export OPTIONAL, leave blank and the default template will be used
- name: timezone_offset
in: query
type: string
responses:
'404':
description: Ticket Not found
/api/v1/{customer_id}/projects/{project_id}/tickets/{uuid}/clone:
post:
summary: Clone a ticket
tags:
- Tickets
description: Copy all the content of a ticket in a new one.
produces:
- application/json
security:
- apiKey: []
parameters:
- name: customer_id
in: path
type: string
required: true
- name: project_id
in: path
type: string
required: true
- name: uuid
in: path
type: string
description: UUID of the ticket to be cloned
required: true
- name: clone_data
in: body
schema:
type: object
properties:
data:
type: object
properties:
attributes:
type: object
properties:
uuid:
type: string
description: New ticket UUID, leave blank, a new UUID will be generated
plan-x:
type: number
description: The new plan-x position of the new ticket
plan-y:
type: number
description: The new plan-y position of the new ticket
required:
- uuid
responses:
'404':
description: Ticket Not found
definitions:
Ticket:
type: object
properties:
ticket-type-id:
type: string
description: ID of the form used in this ticket
component-id:
type: string
description: ID of the layer to add this ticket to
subject:
type: string
example: Ticket title
description: Ticket title, leave empty the default title will be used instead
parent-id:
type: string
description: If you are creating a child ticket, set it to the UUID of the parent ticket
status-id:
type: string
minimum: 1
maximum: 6
example: 1
description: The status of the ticket, the default is Open
priority-id:
type: string
minimum: 1
maximum: 3
example: 1
description: The priority of the ticket, the default is normal
assigned-to-id:
type: string
description: The id or the object of the assignee
example:
legacy: 1
object:
id: 1
type: User | DefectradarGroup
assignee-type:
type: string
description: User OR DefectradarGroup (redundant if assigned-to-id is set to an object)
due-date:
type: date
description: Ticket due date
closed-at:
type: date
description: Ticket closed at date
extension-date:
type: string
description: Extenstion date, should always be bigger that the due date
typed-values:
type: object
example:
tf37e04757dabbca63: 33.5
tfd4367f50e84a9408: some text
tf00a1b2c3d4e5f601: 1
description: The custom defined field values, based on the selected form. Value types depend on the field type (e.g. string for text fields, number for numeric fields, integer 1-3 for CheckListType fields)
subscribers:
type: array
items:
type: integer
description: array of user IDs that are subscribed to this ticket
progress:
type: integer
minimum: 0
maximum: 100
plan-x:
type: number
description: is used to position the ticket on the plan
plan-y:
type: number
description: is used to position the ticket on the plan
uuid:
type: string
description: The unique identifier of the ticket, leave blank and a UUID will be generated
required:
- ticket-type-id
- component-id
securityDefinitions:
apiKey:
type: apiKey
name: X-PlanRadar-API-Key
in: header
externalDocs:
description: Find out more about our development portal
url: https://www.planradar.com/knowledge-base-overview/