Skip to content
Browse API reference

Create a new List Item

Request

POST https://api.castle.io/v1/lists/{list_id}/items

Path parameters

list_idrequired
string

ID of the List

Request body

primary_value
required
string

Value of the primary_field as described by the List definition. For example, if primary_field is configured to be the Event user.id, the primary_value on the List Item referes to the actual User ID value.

secondary_value
string | null

Optional secondary value. If this value is set, it means that for a List Item to match an Event, both the primary_value and secondary_value must match.

comment
string

An arbitrary string that can be used to eg. explain why this List Item was created. Often useful to display to other users.

author
required
object

Indicates who or how the list item was created. Typically, this refers to the user that created the item from within the Castle Dashboard, or the policy ID if it was automatically created via automation.

auto_archives_at
string (date-time) | null

Time after which a the List Item will be automatically archived and no longer matched against each event. A value of null means auto archivation is disabled and the record will stay active in the list forever.

mode
stringDefault: error

Describes a strategy to use when a List Item with the same (primary, secondary) values is already in the List. Available strategies:

  • $error - return a 422 HTTP error
  • $replace - archive the existing List Item and create a new one
  • $update - if the author matches the existing List Item, update it. Otherwise, throw an HTTP 422 error.
  • $update_or_replace - if the author matches the existing List Item, update it. Otherwise, archive the existing List Item and create a new one.
$error$replace$update$update_or_replace

Response

201
object

Returns the newly created List Item

401
No body

You are missing the Authorization header, or the API secret is missing or incorrect.

403
No body

The request is rejected because the service is not enabled for this account.

422
object

The request body is unprocessable by the API. Make sure it conforms to the specified format for the endpoint.

429
No body

You performed too many requests. You should back off and retry using the exponential backoff algorithm.

500
No body

There’s an issue on our end.