Some endpoints are able to return more data than they normally do by expanding their response. When this is possible the endpoint will specify the expand field and will document which fields can be expanded. The expand field takes an array of string field names that identify which fields you wish to expand.

To expand a single field, you may specify it as part of the query.

For example:

/example-endpoint?expand[]=bar

This will cause the bar key and its value to be included in the response. If bar itself has expandable fields, see path expands.

If the field you wish to expand is not a top level key within the response, you may specify it using dot notation.

For example:

/example-endpoint?expand[]=foo.bar

If foo itself is not an expandable field, this will work like a normal field expand. The bar key and its value will be included in the response nested under the foo key.

If foo is an expandable field, see nested expands.

To expand more than one field, you may add additional expands to the query.

For example:

/example-endpoint?expand[]=bar&expand[]=baz

If you are already expanding a field, foo, and it has its own expandable field(s), bar, you may additionally expand bar as follows.

/example-endpoint?expand[]=foo&expand[]=foo.bar

The foo key and its value will be included in the response. Additionally, The bar key and its value will be included in the response nested under the foo key.

If you wish to expand the bar key, but are not interested in the other keys on foo, see granular expands.

If foo is an expandable field whose keys you are not interested in except for its own expandable field bar, you may do the following.

/example-endpoint?expand[]=foo.bar

The foo key will exist, but its value will only have the bar key, discluding all other sibling keys you did not explicitly ask for.

Some endpoints specify a search parameter. The value of this parameter must be a string that contains a valid query as defined by this search query language.

A query consists of at least one and at most five clauses joined by the and keyword.

For example:

inserted_at>='2023-01-01T00:00:00Z' and description~'east blue'

A clause consists of a key, an operator, and a value.

For example:

inserted_at>='2023-01-01T00:00:00Z'

When performing a search, the set of valid keys is defined by the relevant endpoint's search parameter's documentation.

Each key an endpoint specifies as searchable will be associated with a set of operators that are valid to use with it. Below are all possible operators and their associated operation:

Each key will specify which type of value it acepts.

String

You must use single quotes when supplying a string. You can escape single quotes inside of single quotes with a backslash (\).

For example:

summary~'zoro\'s three sword style'

Boolean

Boolean values are supplied either true or false without single quotes.

For example:

archived:true

Date-Time

You must use single quotes when supplying a date-time and you must use the following representation: '[YYYY]-[MM]-[DD]T[HH]:[MM]:[SS]Z'. The timezone is always UTC.

For example:

inserted_at:'2023-01-01T00:00:00Z'

Numeric

Numeric values are supplied as-is without single quotes.

For example:

berries:100000000

Use signing keys instead.

This functionality has been superceded by artifacts, artifact versions, and binaries.