openapi: 3.1.0
info:
title: Events API
version: 3.0.0
description: Provides the audit trail of events for the organization.
contact:
name: Sendcloud API Support
url: https://www.sendcloud.dev
email: contact@sendcloud.com
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://panel.sendcloud.sc/api/v3
description: Sendcloud Production
tags:
- name: Events
paths:
/events:
get:
summary: Retrieve a list of events
description: |-
Retrieves a list of events for the authenticated organization.
This endpoint uses cursor-based pagination via `Link` headers. See [Pagination](/api/v3/pagination) for details.
x-mint:
href: /api/v3/events/retrieve-a-list-of-events
metadata:
tag: Beta
content: |-
OAuth2 scopes required: `read:audit-log`. See [Scopes for OAuth apps](/api/v3/scopes).
operationId: sc-public-v3-events-get-events
tags:
- Events
parameters:
- $ref: '#/components/parameters/Cursor'
- schema:
type: integer
maximum: 100
in: query
name: page_size
description: The size of the page to fetch.
example: 100
- schema:
type: string
enum:
- shipment
in: query
name: resource_type
description: Filter events by resource type.
example: shipment
- schema:
type: string
in: query
name: resource_id
description: Filter events by the identifier of the affected resource.
example: '12345'
- schema:
type: string
enum:
- create
- update
- delete
in: query
name: operation
description: Filter events by operation type.
example: create
- schema:
type: string
format: date-time
in: query
name: start_datetime
description: Include events at or after this timestamp (ISO 8601).
example: '2024-01-01T00:00:00Z'
- schema:
type: string
format: date-time
in: query
name: end_datetime
description: Include events at or before this timestamp (ISO 8601).
example: '2024-12-31T23:59:59Z'
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds:
- read:audit-log
x-sendcloud-paginated: true
x-sendcloud-paginated-discriminator: data
responses:
'200':
description: OK
headers:
Link:
description: The pagination links, according to the web linking specification (RFC8288).
schema:
type: string
example: ; rel="prev", ; rel="next"
content:
application/json:
schema:
type: object
properties:
data:
type: array
description: A list of events for the organization.
items:
$ref: '#/components/schemas/Event'
example:
data:
- user_id: 123456
organization_id: 789012
resource_type: shipment
operation: create
resource_id: b7c82d93-4429-5992-9806-561d848dg3b5
timestamp: '2026-06-15T11:11:41.484461Z'
'403':
description: Forbidden
content:
application/json:
schema:
type: object
description: Standardized format for errors in JSON:API responses.
properties:
errors:
type: array
items:
$ref: '#/components/schemas/ErrorObject'
required:
- errors
example:
errors:
- status: '403'
code: authentication_failed
detail: Authentication credentials were not provided.
components:
securitySchemes:
HTTPBasicAuth:
type: http
description: Basic Authentication using API key and secrets is currently the main authentication mechanism.
scheme: basic
OAuth2ClientCreds:
type: oauth2
description: OAuth2 is a standardized protocol for authorization that allows users to share their private resources stored on one site with another site without having to provide their credentials. OAuth2 Client Credentials Grant workflow. This workflow is typically used for server-to-server interactions that require authorization to access specific resources.
flows:
clientCredentials:
tokenUrl: https://account.sendcloud.com/oauth2/token/
scopes:
read:analytics: View your shipping analytics
read:audit-log: View your account's audit log
read:brand: View your brands
write:brand: Manage your brands
write:carrier: Configure carriers and contracts
read:checkout: View your dynamic checkout configurations and templates
read:event-subscription: View your event subscriptions
write:event-subscription: Create and manage your event subscriptions
read:integration: View your integrations
write:integration: Connect and manage integrations
read:invoice: View your invoices
read:notification: View your notifications
write:notification: Manage your notifications
read:operational-settings: View your warehouses, shipping lanes, and other operational settings
write:operational-settings: Manage your warehouses, shipping lanes, and other operational settings
read:order: View your orders
write:order: Import and process your orders
read:organization: View organization settings
write:organization: Change organization settings
read:parcel: View your shipments and their tracking status
write:parcel: Create, announce, and cancel shipments
read:pickup: View carrier pickups and the options available for scheduling them
write:pickup: Schedule and manage carrier pickups
read:price: View shipping prices
write:product: Manage your product catalog
read:return: View your returns
write:return: Create and manage returns
read:return-settings: View your return settings
write:return-settings: Configure your return settings
read:service-point: View carrier service points
read:shipping-method: View shipping methods, products and prices
read:shipping-rule: View your shipping rules
write:shipping-rule: Create and manage shipping rules
read:support-ticket: View your support tickets
write:support-ticket: Manage your support tickets
read:tracking-message: View your tracking notifications
write:tracking-message: Manage your tracking notifications
read:tracking-page: View your tracking page
write:tracking-page: Customize your tracking page
read:user: Read your basic account information
schemas:
Event:
description: Schema representing a single event. An event is a record of something that occurred in the system, such as a user creating a shipment or an automated process updating a resource.
type: object
title: Event
properties:
user_id:
type:
- integer
- 'null'
description: The ID of the user who performed the action. Null for system-initiated actions.
example: 42
actor_id:
type:
- integer
- 'null'
description: The ID of the actor who performed the action. Null for system-initiated actions. The actor can differ from the user in case the action was performed on behalf of another user (e.g., an admin performing an action for a regular user).
example: 42
organization_id:
type: integer
description: The ID of the organization the event belongs to, automatically scoped to the authenticated organization.
example: 1001
resource_type:
type: string
enum:
- shipment
description: The type of resource affected by the event.
example: shipment
operation:
type: string
enum:
- create
- update
- delete
description: The operation performed on the resource.
example: create
resource_id:
type: string
description: The identifier of the affected resource.
example: '12345'
timestamp:
type: string
format: date-time
description: The time at which the event occurred (ISO 8601).
example: '2024-06-17T10:30:00Z'
required:
- organization_id
- resource_type
- operation
- resource_id
- timestamp
ErrorObject:
title: Error
type: object
description: Error in a JSON:API error format
properties:
id:
type: string
description: A unique identifier for the error.
links:
type: object
description: A set of hyperlinks that provide additional information about the error.
properties:
about:
type: string
description: A URL that provides additional information about the error.
status:
type: string
format: int32
description: The HTTP status code of the error.
minLength: 1
code:
type: string
description: A unique error code for the error, in snake case format.
minLength: 1
enum:
- unknown_field
- invalid
- forbidden
- invalid_choice
- min_value
- 'null'
- not_found
- required
- not_a_list
- non_field_errors
- authentication_failed
- validation_error
- parcel_announcement_error
title:
type: string
description: A short, human-readable summary of the error.
minLength: 1
detail:
type: string
description: A human-readable explanation of the error.
minLength: 1
source:
type: object
description: An object that identifies the source of the error within the request payload.
properties:
pointer:
type: string
description: A `JSON` pointer to the location of the error within the request payload.
parameter:
type: string
description: The name of the `query` parameter that caused the error.
header:
type: string
description: The name of the `header` parameter that caused the error.
meta:
type: object
description: Additional metadata about the error.
parameters:
Cursor:
in: query
name: cursor
description: |-
The cursor query string is used as the pivot value to filter results. If no value is provided, the first page of results will be returned. To get this value, you must encode the offset, reverse and position into a base64 string.
There are 3 possible parameters to encode:
- `o`: Offset
- `r`: Reverse
- `p`: Position
For example, `r=1&p=300` encoded as a base64 string would be `cj0xJnA9MzAw`. The query string would then be `cursor=cj0xJnA9MzAw`.
schema:
type: string
example: cj0xJnA9MzAw