Requests & responses¶

Compressed requests¶

To send a large body in fewer bytes, compress it with gzip and set the Content-Encoding: gzip header. The API inflates the body before it reads it, so the Content-Type and the body stay the same as in an uncompressed request.

gzip -c portfolio.json > portfolio.json.gz

curl https://api.everysk.com/v2/portfolios \
  -H "Content-Type: application/json" \
  -H "Content-Encoding: gzip" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  --data-binary @portfolio.json.gz \
  -X POST

Compression reduces the size on the wire, not the payload limit: once inflated, the body must still fit the maximum payload size. Use --data-binary, not -d, so curl sends the compressed bytes untouched.

Case	Response
`Content-Encoding: gzip`	The body is inflated and the request runs as usual.
Any other value, such as `x-gzip`, `deflate` or `gzip, deflate`	`400` with `unsupported Content-Encoding`.
A body that is truncated or is not valid gzip	`400` with `malformed compressed request body`.

Responses are compressed too when the request sends Accept-Encoding: gzip. Most HTTP clients send it and inflate the response on their own. With curl, add --compressed.

Response headers¶

Example of HTTP header response:

HTTP/2 200
content-type: application/json; charset=utf-8
x-everysk-request-id: ed888caa18904ca5b5f05e305ab11551
x-everysk-request-duration: 81.3500881195
x-everysk-rate-limit-allowed: 60
x-everysk-rate-limit-remaining: 49
x-everysk-rate-limit-reset: 10

Every API response carries the headers below. If you need to contact us about a specific request, include its X-Everysk-Request-Id so we can find it quickly.

Header	Description
`X-Everysk-Request-Id`	A unique identifier for the request.
`X-Everysk-Request-Duration`	The time Everysk servers spent processing the request, in milliseconds.
`X-Everysk-Rate-Limit-Allowed`	The number of requests you are allowed per `1 minute` window.
`X-Everysk-Rate-Limit-Remaining`	The number of requests you can make before hitting the limit.
`X-Everysk-Rate-Limit-Reset`	The time left before the rate limit window resets, in seconds.

Rate limits¶

Example on how to check the remaining requests in the current window:

curl -i https://api.everysk.com/v2/health_check \
  -G

Example rate limit error response:

{
  "code": 429,
  "message": "Too Many Requests - You've exceeded the rate limit for your api account SID. Please try again using truncated exponential backoff."
}

Everysk API is rate-limited to 120 requests per minute as default. This safety limit is set by Everysk to protect the integrity of our system. If you exceed the limit established in your plan, any request you send will return a 429 error: "Too Many Requests". If you require a higher limit, please contact us.

The X-Everysk-Rate-Limit-* response headers tell you where you stand in the current window.

Pagination¶

All top-level API resources have support for bulk fetches via "list" API methods. These list API methods share a common structure, taking at least these two parameters: page_size and page_token.

Everysk utilizes cursor-based pagination via the page_token. The page_token parameter returns objects listed after the named object in reverse chronological order.

Parameter	Description
`page_size` integer	optional, default is `10` The number of objects to return, between 1 and 100.
`page_token` string	optional, default is `null` The `next_page_token` of the previous response. Leave it out for the first page.

Every list response carries next_page_token. Repeat the same request with that value in page_token to fetch the next page. When next_page_token is null, there are no more pages.

{
  "portfolios": [...],
  "next_page_token": "Cj0SN2oOc35ldmVyeXNrLWFwcHIlCxIJUG9ydGZvbGlvIhZwb3J0X2RydXlabVlwSHNYYmdUYkM4..."
}

Filter with query¶

The query parameter of a list takes one text, and its first character decides what it filters:

`query`	Returns
An id, such as `port_druyZmYpHsXbgTbC8IMmS4B2Q`	That one entity, in a list.
`#` and tags, such as `#april #sample`	The entities that carry every one of the tags.
`&` and a link UID, such as `&positions-feed`	The entities with that `link_uid`.
Any other text, such as `Global`	The entities whose name starts with the text.

curl "https://api.everysk.com/v2/files?workspace=main" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  --data-urlencode "query=&positions-feed" \
  -G

Encode the value in the URL: # and & have their own meaning there. With curl, pass it with --data-urlencode, as above.

Filter by period¶

Lists also take a period. It filters the entity's business date, or when it last changed, updated_on:

Parameter	Description
`start` string	optional, default is `null` Returns entities from this date onward. `20260831` starts at the first instant of the day, `20260831 12:55:51` at that second.
`end` string	optional, default is `null` Returns entities up to this date. `20260831` runs to the last instant of the day, `20260831 18:00:00` to the end of that second.
`date_time` string	optional, default is `null` Sets `start` and `end` to the same value. With a day, such as `20260901`, it returns that day.
`period_field` string	optional, default is `date` The property the period filters: `date` or `updated_on`. Entities without a `date`, such as Custom Index, Private Security and User App, only take `updated_on`, which is then the default.

Dates are in UTC, and both bounds are inclusive. A time of day only counts with updated_on, since date is a day. A period on date does not combine with a name search: send period_field=updated_on instead.

curl "https://api.everysk.com/v2/portfolios?workspace=main&start=20260801&end=20260831" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -G

Filter with an SDK query¶

For more than one condition, query also takes a JSON object in the shape of the Python SDK's Query. It combines filters, sorts the results and picks the properties each entity returns:

curl https://api.everysk.com/v2/portfolios \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  --data-urlencode 'query={
    "filters": [
      ["workspace", "=", "main"],
      ["tags", "=", ["risk"]],
      ["date", ">=", "20260801"]
    ],
    "order": ["-date"],
    "projection": ["name", "date", "tags"],
    "page_size": 50
  }' \
  -G

Key	Description
`filters` array	Conditions that must all hold, each `[property, operator, value]`. The operators are `=`, `<`, `<=`, `>`, `>=` and `IN`, which takes a list.
`order` array	The properties to sort by. Prefix a property with `-` for descending order.
`projection` array	The properties to return, such as `["name", "date"]`, or the ones to leave out, prefixed with `-`, such as `["-securities"]`. Do not mix the two.
`distinct_on` array	Properties whose value each returned entity must not repeat.
`page_size` integer	The number of objects to return per page. A `page_size` in the URL takes precedence.

The JSON query applies only the filters it lists, so add ["workspace", "=", "main"] to scope it to a workspace. Page with page_token in the URL, as with any list.

Where each filter applies¶

Resource	Pagination	`query` text	Period	SDK query
Portfolio
Datastore
File
Custom Index
Private Security
User App
Report
Worker Template
Audit Log

Errors¶

An error response example:

{
  "code": 400,
  "message": "Bad Request - Please visit https://www.everysk.com/api/docs for more information."
}

The API uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, etc.), and codes in the 5xx range indicate an error with Everysk's servers.

HTTP Status Code Summary:

Code	Message	Description
`200`	`OK`	Everything worked as expected.
`400`	`Bad Request`	The request was unacceptable. This could be due to a missing required field, an invalid parameter or another issue.
`401`	`Unauthorized`	No valid credentials provided.
`403`	`Forbidden`	The credentials provided do not have permission to access the requested resource.
`404`	`Not Found`	The requested resource doesn't exist.
`429`	`Too Many Requests`	Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
`5XX`	`Server Errors`	Something went wrong with Everysk Servers.