Package API

This API allows you to manage packages in the system. It provides endpoints to create, read, update, and delete packages, as well as perform specific operations like marking packages as stale and managing attachments.

Data packages are used to store structured or unstructured information in the system. They can store reports, documents, external data, and more.

The Package Object

The Package object represents a content package in the system.

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "borrowerId": "789e4567-e89b-12d3-a456-426614174111",
  "dealId": "321e4567-e89b-12d3-a456-426614174333",
  "assetId": "654e4567-e89b-12d3-a456-426614174444",
  "sourceId": "456e4567-e89b-12d3-a456-426614174222",
  "alias": "monthly_report",
  "workflowId": "workflow123",
  "label": "Monthly Report",
  "contentType": "json",
  "tags": ["report", "monthly"],
  "createdAt": "2023-04-01T12:00:00Z",
  "ttl": "2023-04-08T12:00:00Z",
  "hasAttachments": true,
  "forcedStale": false
}

Attributes

Attribute	Description	Type
`id`	Unique identifier for the package	String
`borrowerId`	Associated borrower's ID (optional)	String
`dealId`	Associated deal's ID (optional)	String
`assetId`	Associated asset's ID (optional)	String
`sourceId`	Source ID of the package (optional)	String
`alias`	Alias for the package (optional)	String
`workflowId`	Associated workflow ID (optional)	String
`label`	Package label or name	String
`contentType`	Type of content in the package	String
`tags`	List of tags associated with the package	Array of Strings
`createdAt`	Package creation date and time	String (ISO 8601)
`ttl`	Time-to-live for the package (optional)	String (ISO 8601)
`hasAttachments`	Indicates whether the package has attachments	Boolean
`forcedStale`	Indicates whether the package is marked as stale. Stale packages are excluded from queries by default.	Boolean

Available Operations

Create a New Package

Creates a new package in the system.

POST /v1/stores/packages

Input Parameters

Parameter	Description	Type	Required
`borrowerId`	Associated borrower's ID	String	No
`dealId`	Associated deal's ID	String	No
`assetId`	Associated asset's ID	String	No
`sourceId`	Source ID of the package	String	No
`workflowId`	Associated workflow ID	String	No
`alias`	Alias for the package	String	No
`label`	Label or name of the package	String	No
`tags`	List of tags for the package	Array of Strings	No
`content`	Content of the package	Any	Yes
`contentType`	Type of content in the package	String	No
`ttlMinutes`	Time-to-live for the package in minutes	Integer	No

Example Request

{
  "borrowerId": "789e4567-e89b-12d3-a456-426614174111",
  "dealId": "321e4567-e89b-12d3-a456-426614174333",
  "assetId": "654e4567-e89b-12d3-a456-426614174444",
  "sourceId": "456e4567-e89b-12d3-a456-426614174222",
  "alias": "monthly_report",
  "label": "Monthly Report",
  "tags": ["report", "monthly"],
  "content": {"data": "report content"},
  "contentType": "json",
  "ttlMinutes": 10080
}

Successful Response

{
  "id": "123e4567-e89b-12d3-a456-426614174000"
}

Retrieve a Package

Gets details about a specific package.

GET /v1/stores/packages/:package_id

Path Parameters

Parameter	Description
`package_id`	ID of the package

Successful Response

Returns the full Package object, as described above.

Retrieve Package Content

Gets the content of a specific package.

GET /v1/stores/packages/:package_id/content

Path Parameters

Parameter	Description
`package_id`	ID of the package

Successful Response

Returns the package's content in the format specified by its contentType.

Delete a Package

Deletes a package from the system.

DELETE /v1/stores/packages/:package_id

Path Parameters

Parameter	Description
`package_id`	ID of the package

Successful Response

HTTP status code 204 (No Content) if deletion is successful.

Mark Packages as Stale

Marks packages matching specified criteria as stale. Stale packages are excluded from query results by default, making this useful for invalidating cached data without deleting it.

PUT /v1/stores/packages/stale

Input Parameters

Parameter	Description	Type	Required
`packageId`	ID of a specific package to mark	String	No*
`alias`	Mark packages with this alias	String	No*
`workflowId`	Mark packages for this workflow	String	No*
`borrowerId`	Mark packages for this borrower	String	No*
`dealId`	Mark packages for this deal	String	No*
`assetId`	Mark packages for this asset	String	No*
`sourceId`	Mark packages from this source	String	No*
`forcedStale`	Must be set to `true`	Boolean	Yes

*At least one filter parameter must be provided. When packageId is provided, it marks only that specific package. When using other filters, validation requires a combination of identifiers (e.g., borrowerId, dealId, or assetId along with alias, workflowId, and sourceId).

Example Request - Mark by Package ID

{
  "packageId": "123e4567-e89b-12d3-a456-426614174000",
  "forcedStale": true
}

Example Request - Mark by Multiple Criteria

{
  "alias": "monthly_report",
  "workflowId": "workflow123",
  "borrowerId": "789e4567-e89b-12d3-a456-426614174111",
  "sourceId": "456e4567-e89b-12d3-a456-426614174222",
  "forcedStale": true
}

Successful Response

HTTP status code 204 (No Content) if the update is successful.

List Packages

Retrieves a paginated list of packages with filtering and sorting options.

GET /v1/stores/packages

Stale Package Filtering: By default, packages marked as stale (forcedStale: true) are excluded from query results. To include stale packages in the results, use the include-stale=true query parameter.

Query Parameters

Parameter	Description	Type	Default
`search`	Text to search within packages	String
`page`	Page number	Integer	1
`per-page`	Items per page	Integer	10
`borrower-id`	Filter by borrower ID	String
`deal-id`	Filter by deal ID	String
`asset-id`	Filter by asset ID	String
`workflow-id`	Filter by workflow ID	String
`source-id`	Filter by source ID	String
`alias`	Filter by alias	String
`source-version`	Filter by source version	String
`from-date`	Filter by start date	String
`to-date`	Filter by end date	String
`sort-by`	Field to sort by	String
`sort-direction`	Sort direction (asc or desc)	String	desc
`include-stale`	Include stale packages in results	Boolean	false

Successful Response

The response will be a paginated list of Package objects. The total count is returned in the X-Total-Count response header.

Add Attachment to a Package

Adds an attachment to an existing package.

POST /v1/stores/packages/:package_id/attachments

Path Parameters

Parameter	Description
`package_id`	ID of the package

Input Parameters

Parameter	Description	Type	Required
`url`	URL of the attachment	String	Yes
`label`	Label for the attachment	String	No
`fileExtension`	File extension	String	No
`metadata`	Additional metadata for the file	Object	No

Example Request

{
  "url": "https://example.com/attachment.pdf",
  "label": "Supporting Document",
  "fileExtension": "pdf",
  "metadata": {
    "description": "Additional information for the monthly report"
  }
}

Successful Response

HTTP status code 201 (Created) if the attachment was added successfully.

Retrieve Package Attachments

Retrieves the list of attachments for a specific package.

GET /v1/stores/packages/:package_id/attachments

Path Parameters

Parameter	Description
`package_id`	ID of the package

Successful Response

The response will be a list of Attachment objects associated with the package.

Delete an Attachment from a Package

Deletes a specific attachment from a package.

DELETE /v1/stores/packages/:package_id/attachments/:attachment_id

Path Parameters

Parameter	Description
`package_id`	ID of the package
`attachment_id`	ID of the attachment

Successful Response

HTTP status code 204 (No Content) if the deletion is successful.

Error Handling

The API may return the following error codes:

Code	Description
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
500	Internal Server Error

Errors will include a descriptive message in the response body.

On this page