OpenAPI SpecificationJSON
API Reference

Hook Run

A hook run is a record of hook execution (log). For easy and efficient development process of the extensions, the backend logs requests, responses (if enabled) and additional information, when the hook is being called.

The retention policy for the logs is set to 7 days.

Hook logs response

Attribute
Type
Description
results*
list[object]
timestamp
datetime

Timestamp of the log entry.

request_id
string

Request ID of the hook call.

event
string

Event that triggered the hook.

action
string

Action that was performed.

annotation_id
integer | null

ID of the related annotation.

Only present for annotation_content and annotation_status events.

queue_id
integer | null

ID of the related queue.

email_id
integer | null

ID of the related email.

Only present for email events.

hook_id
integer

ID of the hook.

hook_type
string

Type of the hook.

message
string

Log message.

request
string

Request payload.

response
string

Response payload.

start
datetime

Start timestamp.

end
datetime

End timestamp.

settings
string

Hook settings.

status
"waiting" | "running" | "completed" | "cancelled" | "failed"

Status of the hook call.

uuid
string

UUID of the hook call.

pagination*
object
next
URL

URL for the next page of results. Contains an opaque signed cursor query parameter. Use this URL directly to fetch the next page — do not attempt to construct or modify the cursor value.

previous
URL

URL for the previous page of results. Contains an opaque signed cursor query parameter. Use this URL directly to fetch the previous page — do not attempt to construct or modify the cursor value.

List hook runs

GET api / v1 / hooks / runs

List recent hook runs with optional filters and pagination.

The logs are sorted by the start timestamp in descending order.

The retention policy for the logs is set to 7 days.

GET
/api/v1/hooks/runs
curl -X GET "https://example.rossum.app/api/v1/hooks/runs?request_id=6166deb3-2f89-4fc2-9359-56cc8e3838e4&uuid=a1b2c3d4-e5f6-7890-abcd-ef1234567890&hook=1500&timestamp_before=2023-09-23T12%3A00%3A00.000000Z&timestamp_after=2023-09-23T12%3A00%3A00.000000Z&start_before=2023-09-23T12%3A00%3A00.000000Z&start_after=2023-09-23T12%3A00%3A00.000000Z&status=completed&status_code=200&email=1&search=error&page_size=50"
{
  "results": [
    {
      "timestamp": "2023-09-23T12:00:00.000000Z",
      "request_id": "6166deb3-2f89-4fc2-9359-56cc8e3838e4",
      "event": "annotation_content",
      "action": "updated",
      "annotation_id": 1,
      "queue_id": 1,
      "email_id": 1,
      "hook_id": 1,
      "hook_type": "webhook",
      "message": "message",
      "request": "{}",
      "response": "{}",
      "start": "2023-09-23T12:00:00.000000Z",
      "end": "2023-09-23T12:00:00.000000Z",
      "settings": "{}",
      "status": "completed",
      "uuid": "6166deb3-2f89-4fc2-9359-56cc8e3838e4"
    }
  ],
  "pagination": {
    "next": null,
    "previous": null
  }
}
{
  "detail": "Bad Request.",
  "code": "bad_request"
}
{
  "detail": "Invalid token.",
  "code": "authentication_failed"
}
{
  "detail": "Access to the requested resource is forbidden.",
  "code": "access_forbidden"
}
{
  "detail": "Not found.",
  "code": "not_found"
}
{
  "detail": "Conflict.",
  "code": "conflict_status"
}
{
  "detail": "Request was rate limited.",
  "code": "rate_limited",
  "url": "https://rossum.app/api/docs/openapi/guides/overview/#rate-limiting"
}
{
  "detail": "Server error.",
  "code": "error"
}
{
  "detail": "Bad Gateway.",
  "code": "bad_gateway"
}
{
  "detail": "Service Unavailable.",
  "code": "service_unavailable"
}
{
  "detail": "Gateway timeout.",
  "code": "gateway_timeout"
}

Response

200OK

OK

Attribute
Type
Description
results*
list[object]
timestamp
datetime

Timestamp of the log entry.

request_id
string

Request ID of the hook call.

event
string

Event that triggered the hook.

action
string

Action that was performed.

annotation_id
integer | null

ID of the related annotation.

Only present for annotation_content and annotation_status events.

queue_id
integer | null

ID of the related queue.

email_id
integer | null

ID of the related email.

Only present for email events.

hook_id
integer

ID of the hook.

hook_type
string

Type of the hook.

message
string

Log message.

request
string

Request payload.

response
string

Response payload.

start
datetime

Start timestamp.

end
datetime

End timestamp.

settings
string

Hook settings.

status
"waiting" | "running" | "completed" | "cancelled" | "failed"

Status of the hook call.

uuid
string

UUID of the hook call.

pagination*
object
next
URL

URL for the next page of results. Contains an opaque signed cursor query parameter. Use this URL directly to fetch the next page — do not attempt to construct or modify the cursor value.

previous
URL

URL for the previous page of results. Contains an opaque signed cursor query parameter. Use this URL directly to fetch the previous page — do not attempt to construct or modify the cursor value.

400Bad Request

Invalid input data.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

401Unauthorized

The username/password is invalid or token is invalid (e.g. expired).

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

403Forbidden

Insufficient permission, missing authentication, invalid CSRF token and similar issue.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

404Not Found

The specified resource was not found.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

409Conflict

Conflict

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

429Too Many Requests

Request rate is too high, wait before sending more requests. See Rate Limiting for more details.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

url
read-only
string

Link to the rate limiting documentation

500Internal Server Error

Server failure while processing the request.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

502Bad Gateway

Invalid response from the upstream server.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

503Service Unavailable

We're temporarily offline for maintenance. Please try again later.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

504

Upstream server could not complete the request in time.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

List hook run logs

GET api / v1 / hooks / runs / {runUuid} / logs

List progress logs related to the specific hook run. The logs are sorted by the timestamp in ascending order.

GET
/api/v1/hooks/runs/{runUuid}/logs
curl -X GET "https://example.rossum.app/api/v1/hooks/runs/d5d021b3-cb12-4253-9f5f-6e8101fe1f42/logs"
{
  "results": [
    {
      "timestamp": "2023-09-23T12:00:00.000000Z",
      "details": "Master Hub data update started"
    }
  ]
}
{
  "detail": "Bad Request.",
  "code": "bad_request"
}
{
  "detail": "Invalid token.",
  "code": "authentication_failed"
}
{
  "detail": "Access to the requested resource is forbidden.",
  "code": "access_forbidden"
}
{
  "detail": "Not found.",
  "code": "not_found"
}
{
  "detail": "Conflict.",
  "code": "conflict_status"
}
{
  "detail": "Request was rate limited.",
  "code": "rate_limited",
  "url": "https://rossum.app/api/docs/openapi/guides/overview/#rate-limiting"
}
{
  "detail": "Server error.",
  "code": "error"
}
{
  "detail": "Bad Gateway.",
  "code": "bad_gateway"
}
{
  "detail": "Service Unavailable.",
  "code": "service_unavailable"
}
{
  "detail": "Gateway timeout.",
  "code": "gateway_timeout"
}

Response

200OK

OK

Attribute
Type
Description
results
list[object]
timestamp
datetime

Timestamp of the log entry.

details
string

Log details.

400Bad Request

Invalid input data.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

401Unauthorized

The username/password is invalid or token is invalid (e.g. expired).

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

403Forbidden

Insufficient permission, missing authentication, invalid CSRF token and similar issue.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

404Not Found

The specified resource was not found.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

409Conflict

Conflict

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

429Too Many Requests

Request rate is too high, wait before sending more requests. See Rate Limiting for more details.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

url
read-only
string

Link to the rate limiting documentation

500Internal Server Error

Server failure while processing the request.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

502Bad Gateway

Invalid response from the upstream server.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

503Service Unavailable

We're temporarily offline for maintenance. Please try again later.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

504

Upstream server could not complete the request in time.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

deprecated

List hook call logs

GET api / v1 / hooks / logs

⚠️ Deprecated: Use List hook runs instead.

List all the logs from all running hooks with optional filters and pagination.

The logs are sorted by the start timestamp in descending order.

GET
/api/v1/hooks/logs
curl -X GET "https://example.rossum.app/api/v1/hooks/logs?request_id=6166deb3-2f89-4fc2-9359-56cc8e3838e4&log_level=INFO&hook=1500&timestamp_before=2023-09-23T12%3A00%3A00.000000Z&timestamp_after=2023-09-23T12%3A00%3A00.000000Z&start_before=2023-09-23T12%3A00%3A00.000000Z&start_after=2023-09-23T12%3A00%3A00.000000Z&status=completed&status_code=200&email=1&search=error&page_size=50"
{
  "results": [
    {
      "timestamp": "2023-09-23T12:00:00.000000Z",
      "request_id": "6166deb3-2f89-4fc2-9359-56cc8e3838e4",
      "event": "annotation_content",
      "action": "updated",
      "annotation_id": 1,
      "queue_id": 1,
      "email_id": 1,
      "hook_id": 1,
      "hook_type": "webhook",
      "message": "message",
      "request": "{}",
      "response": "{}",
      "start": "2023-09-23T12:00:00.000000Z",
      "end": "2023-09-23T12:00:00.000000Z",
      "settings": "{}",
      "status": "completed",
      "uuid": "6166deb3-2f89-4fc2-9359-56cc8e3838e4"
    }
  ],
  "pagination": {
    "next": null,
    "previous": null
  }
}
{
  "detail": "Bad Request.",
  "code": "bad_request"
}
{
  "detail": "Invalid token.",
  "code": "authentication_failed"
}
{
  "detail": "Access to the requested resource is forbidden.",
  "code": "access_forbidden"
}
{
  "detail": "Not found.",
  "code": "not_found"
}
{
  "detail": "Conflict.",
  "code": "conflict_status"
}
{
  "detail": "Request was rate limited.",
  "code": "rate_limited",
  "url": "https://rossum.app/api/docs/openapi/guides/overview/#rate-limiting"
}
{
  "detail": "Server error.",
  "code": "error"
}
{
  "detail": "Bad Gateway.",
  "code": "bad_gateway"
}
{
  "detail": "Service Unavailable.",
  "code": "service_unavailable"
}
{
  "detail": "Gateway timeout.",
  "code": "gateway_timeout"
}

Response

200OK

OK

Attribute
Type
Description
results*
list[object]
timestamp
datetime

Timestamp of the log entry.

request_id
string

Request ID of the hook call.

event
string

Event that triggered the hook.

action
string

Action that was performed.

annotation_id
integer | null

ID of the related annotation.

Only present for annotation_content and annotation_status events.

queue_id
integer | null

ID of the related queue.

email_id
integer | null

ID of the related email.

Only present for email events.

hook_id
integer

ID of the hook.

hook_type
string

Type of the hook.

message
string

Log message.

request
string

Request payload.

response
string

Response payload.

start
datetime

Start timestamp.

end
datetime

End timestamp.

settings
string

Hook settings.

status
"waiting" | "running" | "completed" | "cancelled" | "failed"

Status of the hook call.

uuid
string

UUID of the hook call.

pagination*
object
next
URL

URL for the next page of results. Contains an opaque signed cursor query parameter. Use this URL directly to fetch the next page — do not attempt to construct or modify the cursor value.

previous
URL

URL for the previous page of results. Contains an opaque signed cursor query parameter. Use this URL directly to fetch the previous page — do not attempt to construct or modify the cursor value.

400Bad Request

Invalid input data.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

401Unauthorized

The username/password is invalid or token is invalid (e.g. expired).

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

403Forbidden

Insufficient permission, missing authentication, invalid CSRF token and similar issue.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

404Not Found

The specified resource was not found.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

409Conflict

Conflict

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

429Too Many Requests

Request rate is too high, wait before sending more requests. See Rate Limiting for more details.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

url
read-only
string

Link to the rate limiting documentation

500Internal Server Error

Server failure while processing the request.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

502Bad Gateway

Invalid response from the upstream server.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

503Service Unavailable

We're temporarily offline for maintenance. Please try again later.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

504

Upstream server could not complete the request in time.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

POSTTrigger manual hook

Previous Page

GETList hook runs

Next Page