Logbook REST APIs
- Last updated
- Save as PDF
Overview
You can use the Logbook RESTful API to create, read, update, and delete logbook entries. All API endpoints are hosted at:
https://api-<your-region>.logbook.planview.com/api/rest/
Replace <your-region> with one of the following based on the hosting location of your environment:
- us
- eu
- ap
For example, if your environment is hosted in the United States, use the following endpoint to call the Log types with configuration API:
https://api-us.logbook.planview.com/api/rest/v1/log-types-with-configs
NOTE
Regarding rate limiting:
- All API endpoints are rate-limited to 500 requests per second per region. If this limit is exceeded, the API will return a "429 Too Many Requests" response.
- Clients should implement retry logic with exponential backoff to handle such scenarios gracefully.
Authentication and authorization
Logbbok API requests require a bearer token obtained using OAuth2 credentials. Follow the steps below to generate and use the token.
- In Planview Admin create an OAuth2 credential for the Logbook integration application.
- Use the OAuth2 credential to obtain an access token. For more information, see OAuth2 Client Credentials.
- Use the access token in API requests by including it in the header of each request as follows:
curl --location 'https://api-us.logbook.planview.com/api/rest/v1/log-types-with-configs' \ --header 'Authorization: Bearer <id_token>'
NOTE
The id_token is valid for the duration specified in the expires_in field (in seconds). You must regenerate the token once it expires to continue using the APIs.
Logbook API
openapi: 3.0.1
info:
title: Logbook API
version: 1.0.0
description: API for managing logs, including custom and system attributes, status, and configurations.
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
schemas:
LogTypesWithConfigsResponse:
type: object
description: >
Response containing a log type ID and its associated system attribute log types.
properties:
id:
type: integer
description: Unique identifier for the log type.
example: 18
log_types:
type: array
description: List of log types with their section configurations.
items:
$ref: "#/components/schemas/LogTypeWithSectionResponse"
system_attribute_log_types:
type: array
description: >
List of system attribute log types associated with this log type.
items:
$ref: "#/components/schemas/SystemAttributesLogTypeResponse"
required:
- id
- log_types
- system_attribute_log_types
LogTypeWithSectionResponse:
type: object
description: >
A log type including section configurations.
properties:
id:
type: integer
example: 18
type_name:
type: string
example: "Decision"
description:
type: string
example: "NO"
is_published:
type: boolean
example: false
is_deleted:
type: boolean
example: false
created_at:
type: string
format: date-time
example: "2024-01-12T09:25:37.853187"
log_type_categories_id:
type: integer
example: 5
log_types_section:
type: array
items:
$ref: "#/components/schemas/LogTypesSection"
required:
- id
- type_name
- is_published
- is_deleted
- created_at
- log_type_categories_id
- log_types_section
LogTypeLogResponse:
type: object
properties:
id:
type: integer
example: 18
type_name:
type: string
example: "Decision"
description:
type: string
example: "NO"
is_published:
type: boolean
example: false
log_type_categories_id:
type: integer
example: 5
allow_email_notification:
type: boolean
example: true
required:
- id
- type_name
- description
- is_published
- log_type_categories_id
- allow_email_notification
LogTypesSection:
type: object
properties:
id:
type: integer
example: 4
is_default_section:
type: boolean
example: true
section_custom_attribute:
type: array
items:
type: object
example: []
required:
- id
- is_default_section
- section_custom_attribute
SystemAttributesLogTypeResponse:
type: object
description: >
System attribute configurations tied to a log type.
properties:
id:
type: string
example: "839"
is_mandatory:
type: boolean
example: false
name:
type: string
example: "Description"
sa_ids:
type: array
items:
type: integer
example: [1]
config_type:
type: string
enum: [longtext, singleselect, multiselect, date]
example: "longtext"
config_value:
type: object
nullable: true
description: "Configuration value for attributes like options for selects"
properties:
options:
type: array
items:
$ref: "#/components/schemas/Option"
required:
- id
- is_mandatory
- name
- sa_ids
- config_type
AppContext:
type: array
items:
type: object
required:
- container_id
- container_source
- container_type
properties:
container_id:
type: integer
container_source:
type: string
container_type:
type: string
LogResponse:
type: object
properties:
id:
type: integer
name:
type: string
log_type:
$ref: "#/components/schemas/LogTypeLogResponse"
custom_attribute_values:
type: object
additionalProperties: true
example:
values:
574:
ca_config_id: 574
section_ca_id: 1969
value:
id: "UUID"
label: "New 02"
value: "New 02"
system_attribute_values:
type: object
additionalProperties: true
example:
values:
1:
id: 3165
sa_id: 1
value:
id: 1
is_visible: true
label: "New"
value: "New"
created_at:
type: string
format: date-time
transferred_from:
$ref: "#/components/schemas/TransferredLog"
transferred_to:
type: array
items:
$ref: "#/components/schemas/TransferredLog"
required:
- id
LogSystemAttributeValueInput:
type: object
required:
- id
- sa_id
properties:
id:
type: integer
example: 3165
sa_id:
type: integer
example: 1
value:
oneOf:
- type: string
example: "<p>test desc</p>"
- type: object
properties:
id:
type: integer
example: 1
is_visible:
type: boolean
example: true
label:
type: string
example: "New"
value:
type: string
example: "New"
- type: object
properties:
avatar:
type: string
format: uri
example: "url"
email:
type: string
format: email
example: "email@example.com"
id:
type: integer
example: 1037
name:
type: string
example: "John Doe"
planview_user_id:
type: string
example: "uuid"
tenant_user_id:
type: string
example: "tid"
- type: array
items:
type: object
properties:
artifact_id:
type: integer
example: 111
artifact_title:
type: string
example: "Card 1"
artifact_type:
type: string
example: "card"
id:
type: integer
example: 111
type:
type: string
example: "mitigation"
- type: string
format: date
example: "2025-05-23"
LogCustomAttributeValueInput:
type: object
properties:
ca_config_id:
type: integer
example: 574
section_ca_id:
type: integer
example: 1969
value:
oneOf:
- type: string
example: "2025-05-22"
- type: object
properties:
id:
type: string
example: "UUID"
label:
type: string
example: "New 02"
value:
type: string
example: "New 02"
example:
id: "UUID"
label: "New 02"
value: "New 02"
- type: array
items:
type: object
properties:
id:
type: string
example: "UUID"
label:
type: string
example: "1"
selected:
type: boolean
example: true
value:
type: string
example: "1"
example:
- id: "UUID"
label: "1"
selected: true
value: "1"
required:
- ca_config_id
- section_ca_id
TransferredLog:
type: object
properties:
id:
type: integer
example: 123
name:
type: string
example: "User A"
planview_user_id:
type: string
example: "uuid"
tenant_user_id:
type: string
example: "tid"
email:
type: string
format: email
example: "user@example.com"
avatar:
type: string
format: uri
example: "https://example.com/avatar.png"
required:
- id
- name
Option:
type: object
properties:
id:
oneOf:
- type: integer
- type: string
example: 1
is_visible:
type: boolean
nullable: true
example: true
label:
type: string
example: "New"
value:
oneOf:
- type: string
- type: integer
example: "New"
required:
- id
- label
- value
security:
- BearerAuth: []
paths:
/api/rest/v1/logs/list:
post:
summary: Get logs of a workspace/work
tags:
- Logs
security:
- BearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
app_context:
$ref: "#/components/schemas/AppContext"
required:
- app_context
responses:
"200":
description: list of logs of that workspace/work
content:
application/json:
schema:
type: object
properties:
rest_logs_data:
type: array
items:
$ref: "#/components/schemas/LogResponse"
/api/rest/v1/logs:
post:
summary: Create multiple or a single log
tags:
- Logs
security:
- BearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
logs:
type: array
items:
type: object
required:
- log_types_id
- name
- app_context
properties:
log_types_id:
type: integer
name:
type: string
transferred_from_id:
type: integer
custom_attribute_values:
type: array
items:
$ref: "#/components/schemas/LogCustomAttributeValueInput"
system_attribute_values:
type: array
items:
$ref: "#/components/schemas/LogSystemAttributeValueInput"
app_context:
$ref: "#/components/schemas/AppContext"
responses:
"200":
description: Log created
content:
application/json:
schema:
type: object
properties:
rest_add_log:
type: object
properties:
Data:
type: array
items:
$ref: "#/components/schemas/LogResponse"
Failed:
type: array
items:
type: object
properties:
failed_message:
type: string
log_types_id:
type: integer
name:
type: string
transferred_from_id:
type: integer
custom_attribute_values:
type: array
items:
$ref: "#/components/schemas/LogCustomAttributeValueInput"
system_attribute_values:
type: array
items:
$ref: "#/components/schemas/LogSystemAttributeValueInput"
app_context:
$ref: "#/components/schemas/AppContext"
/api/rest/v1/log/delete/{log_id}:
post:
summary: Delete single Log
tags:
- Logs
security:
- BearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
app_context:
$ref: "#/components/schemas/AppContext"
required:
- app_context
parameters:
- name: log_id
in: path
required: true
schema:
type: string
description: The ID of Log to delete
responses:
"200":
description: Log delete
content:
application/json:
schema:
type: object
properties:
rest_delete_log:
type: object
properties:
deleted_id:
type: string
example: 4
example:
rest_delete_log:
deleted_id: "123"
"400":
description: Bad request
content:
application/json:
examples:
LogDoesNotExist:
summary: The log does not exist
value:
code: LOG_DOES_NOT_EXIST
message: The log does not exist in the system
LogDeleted:
summary: The log is already deleted
value:
code: LOG_DELETED
message: The log you are trying to delete is already deleted
LogTransferred:
summary: Log has already been transferred
value:
code: LOG_TRANSFERRED
message: Can not delete a log which already been transferred to another type
"401":
description: Unauthorized
content:
application/json:
examples:
InvalidContainer:
summary: The logs does not belong to the container
value:
code: INVALID_CONTAINER
message: The log does not exist in the provided container in app_context
InvalidTenant:
summary: The log does not belong to the tenant
value:
code: INVALID_TENANT
message: The log does not belong to the provided tenant_group
/api/rest/v1/log/{log_id}:
put:
summary: Update single Log
tags:
- Logs
security:
- BearerAuth: []
parameters:
- name: log_id
in: path
required: true
schema:
type: string
description: The ID of Log to update
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- app_context
properties:
name:
type: string
custom_attribute_values:
type: array
items:
$ref: "#/components/schemas/LogCustomAttributeValueInput"
system_attribute_values:
type: array
items:
$ref: "#/components/schemas/LogSystemAttributeValueInput"
app_context:
$ref: "#/components/schemas/AppContext"
responses:
"200":
description: Log updated
content:
application/json:
schema:
type: object
properties:
rest_modify_log:
type: object
$ref: "#/components/schemas/LogResponse"
/api/rest/v1/log-types-with-configs:
get:
summary: Get log types and configurations
tags:
- Configs
security:
- BearerAuth: []
responses:
"200":
description: Log types and their system attribute configurations.
content:
application/json:
schema:
type: object
properties:
rest_log_types_with_configs:
type: array
items:
$ref: "#/components/schemas/LogTypesWithConfigsResponse"
example:
rest_log_types_with_configs:
- id: 101
log_types:
- id: 101
type_name: "Incident"
description: "Incident logs"
is_published: true
is_deleted: false
created_at: "2024-01-12T09:25:37.853187"
log_type_categories_id: 1
log_types_section:
- id: 11
is_default_section: true
section_custom_attribute: []
system_attribute_log_types:
- id: "5"
name: "Priority"
is_mandatory: true
sa_ids: [1]
config_type: "singleselect"
config_value:
options:
- id: "opt1"
label: "High"
value: "High"
- id: "opt2"
label: "Low"
value: "Low"
- id: "6"
name: "Status"
is_mandatory: false
sa_ids: [2]
config_type: "multiselect"
config_value:
options:
- id: "opt1"
label: "Open"
value: "Open"
- id: "opt2"
label: "Closed"
value: "Closed"