Cortex api

Cortex api DEFAULT

Develop with Emotiv

EMotiv Launcher interface

Cortex is our new API powerhouse, enabling you to start creating truly personalized experiences and activations using real-time brain data.

LET’S START BUILDING

Cortex is a wrapper around our Software Development Kit (SDK) and houses all the tools required to develop with EMOTIV. It provides API access to different EMOTIV data streams, tiered out across three license levels. Join our worldwide community of developers and start creating your own application now.

Getting started

Embed brain data into your workplace, products or services using Cortex in four easy steps. Our licensing plans suit a wide variety of needs from providing access to our core data streams for brain-computer interface to high-resolution performance metrics for custom commercial applications.

Apply for the license that best suits your use case.

Once approved by EMOTIV, you will get access to our centralized installer EMOTIV Launcher in your Account.

Register your App in My Account > Cortex Apps.

Receive your App ID, Client ID, Client secret and start building.

Licensing options

We offer three licensing plans to suit a wide variety of needs.

BUILD YOUR APP

Built on JSON and WebSockets, Cortex integrates our headset’s data streams with third-party software enabling you to record data, create BCI applications or build custom games and apps. Use the documentation below or look at some of our featured examples

Here is how our “Cortex Service” works:

developers developer cortex emotiv diagram

DOCUMENTATION & EXAMPLES

Unity Plugin Support is now available. Visit our Github page to learn more.

Use the force

Using an Emotiv Insight, a Sphero BB-8 Droid and IoT services on Bluemix, Joshua Carr demonstrates how you can use your mind to move BB-8 Droids.

Attention Powered Car

An Attention Powered Car was created to raise the issue of driver inattention and road safety. The car features an EPOC headset that connects brain activity to the car’s engine via customized software. When the driver’s level of attention drops, the car safely slows down, alerting the driver to their lapse in concentration.

PUBLISH YOUR APP

If you have created an exciting application with our technology, we’d love to share it with our community. Get in touch with us and we can help you distribute your application to our community.

Free or Open source
Applications (F/OSS)

Contact Customer Support and have your app approved and published in the F/OSS list.

Contact us here

Commercial
Applications (non F/OSS)

Contact our Business Development team to discuss terms and conditions for a distribution license.

Contact us here

Note: Unpublished Apps can only be accessed by the owner or EmotivID associated with that App. Users must sign a new ‘Distribution License’ before they can publish.

Emotiv Newsletter

Exclusive email, discounts & product announcements.

Subscribe
Sours: https://www.emotiv.com/developer/

API Guide

This guide applies only to Cortex 2 and newer. It is not applicable to Cortex 1.

Table of Contents

Introduction

Cortex 2 offers a REST API that can be leveraged by various applications and programs to interact with it. The following guide describe the Cortex 2 API to allow developers to interface the powerful observable analysis engine with other SIRPs (Security Incident Response Platforms) besides TheHive, TIPs (Threat Intelligence Platforms), SIEMs or scripts. Please note that the Web UI of Cortex 2 exclusively leverage the REST API to interact with the back-end.

Note: You can use Cortex4py, the Python library we provide, to facilitate interaction with the REST API of Cortex. You need Cortex4py 2.0.0 or later as earlier versions are not compatible with Cortex 2.

All the exposed APIs share the same request & response formats and authentication strategies as described below.

There are also some transverse parameters supported by several calls, in addition to utility APIs.

If you want to create an analyzer, please read the How to Write and Submit an Analyzer guide.

Request & Response Formats

Cortex accepts several parameter formats within a HTTP request. They can be used indifferently. Input data can be:

  • A query string
  • A URL-encoded form
  • A multi-part
  • JSON

Hence, the requests shown below are equivalent.

Query String

curl -XPOST 'https://CORTEX_APP_URL:9001/api/login?user=me&password=secret'

URL-encoded Form

curl -XPOST 'https://CORTEX_APP_URL:9001/api/login' -d user=me -d password=secret

JSON

curl -XPOST https://CORTEX_APP_URL:9001/api/login -H 'Content-Type: application/json' -d '{ "user": "me", "password": "secret"}'

Multi-part

curl -XPOST https://CORTEX_APP_URL:9001/api/login -F '_json=<-;type=application/json'<<_EOF_{ "user": "me", "password": "secret"}_EOF_

Response Format

For each request submitted, Cortex will respond back with JSON data. For example, if the authentication request is successful, Cortex should return the following output:

{"id":"me","name":"me","roles":["read","analyze","orgadmin"]}

If not, Cortex should return an authentication error:

{"type":"AuthenticationError","message":"Authentication failure"}

Authentication

Most API calls require authentication. Credentials can be provided using a session cookie, an API key or directly using HTTP basic authentication (if this method is specifically enabled).

Session cookies are better suited for browser authentication. Hence, we recommend authenticating with API keys when calling the Cortex APIs.

Generating API Keys with an orgAdmin Account

API keys can be generated using the Web UI. To do so, connect using an account then click on Organization and then on the button in the row corresponding to the user you intend to use for API authentication. Once the API key has been created, click on to display the API key then click on the copy to clipboard button if you wish to copy the key to your system's clipboard.

If the user is not yet created, start by clicking on to create it then follow the steps mentioned above.

Generating API Keys with a superAdmin Account

You can use a account to achieve the same result as described above. Once authenticated, click on Users then on the button in the row corresponding to the user you intend to use for API authentication. Please make sure the user is in the right organization by thoroughly reading its name, which is shown below the user name. Once the API key has been created, click on to display the API key then click on the copy to clipboard button if you wish to copy the key to your system's clipboard.

Authenticating with an API Key

Once you have generated an API key you can use it, for example, to list the Cortex jobs thanks to the following command:

# Using API key curl -H 'Authorization: Bearer **API_KEY**' https://CORTEX_APP_URL:9001/api/job

As you can see in the example above, we instructed to add the Authorization header to the request. The value of the header is . So if your API key is , the command above would look like the following:

# Using API key curl -H 'Authorization: Bearer GPX20GUAQWwpqnhA6JpOwNGPMfWuxsX3' https://CORTEX_APP_URL:9001/api/job

Using Basic Authentication

Cortex also supports basic authentication but it is disabled by default for security reasons. If you absolutely need to use it, you can enable it by adding to the configuration file ( by default). Once you do, restart the Cortex service. You can then, for example, list the Cortex jobs using the following command:

# Using basic authentication curl -u mylogin:mypassword https://CORTEX_APP_URL:9001/api/job

Organization APIs

Cortex offers a set of APIs to create, update and list organizations.

Organization Model

An organization (org) is defined by the following attributes:

AttributeDescriptionType
Copy of the org's name (see next row)readonly
Namereadonly
Status ( or )writable
Descriptionwritable
Creation datecomputed
User who created the orgcomputed
Last updatecomputed
User who last updated the orgcomputed

Please note that and are essentially the same. Also, and are in epoch.

List

It is possible to list all the organizations using the following API call, which requires the API key associated with a account:

curl -H 'Authorization: Bearer **API_KEY**''https://CORTEX_APP_URL:9001/api/organization'

You can also search/filter organizations using the following query:

curl -H 'Authorization: Bearer **API_KEY**' -H 'Content-Type: application/json''https://CORTEX_APP_URL:9001/api/organization/_search' -d '{ "query": {"status": "Active"}}'

Both APIs supports the and query parameters described in paging and sorting details.

Create

It is possible to create an organization using the following API call, which requires the API key associated with a account:

curl -XPOST -H 'Authorization: Bearer **API_KEY**' -H 'Content-Type: application/json''https://CORTEX_APP_URL:9001/api/organization' -d '{ "name": "demo", "description": "Demo organization", "status": "Active"}'

Update

You can update an organization's description and status ( or ) using the following API call. This requires the API key associated with a account:

curl -XPATCH -H 'Authorization: Bearer **API_KEY**' -H 'Content-Type: application/json''https://CORTEX_APP_URL:9001/api/organization/ORG_ID' -d '{ "description": "New Demo organization",}'

or

curl -XPATCH -H 'Authorization: Bearer **API_KEY**' -H 'Content-Type: application/json''https://CORTEX_APP_URL:9001/api/organization/ORG_ID' -d '{ "status": "Active",}'

Delete

Deleting an organization just marks it as and doesn't remove the associated data from the DB. To "delete" an organization, you can use the API call shown below. It requires the API key associated with a account.

curl -XDELETE -H 'Authorization: Bearer **API_KEY**''https://CORTEX_APP_URL:9001/api/organization/ORG_ID'

Obtain Details

This API call returns the details of an organization as described in the Organization model section.

curl -H 'Authorization: Bearer **API_KEY**''https://CORTEX_APP_URL:9001/api/organization/ORG_ID'

Let's assume that the organization we are seeking to obtain details about is called demo. The command would be:

curl -H 'Authorization: Bearer **API_KEY**''https://CORTEX_APP_URL:9001/api/organization/demo'

and it should return:

{ "id": "demo", "name": "demo", "status": "Active", "description": "Demo organization", "createdAt": 1520258040437, "createdBy": "superadmin", "updatedBy": "superadmin", "updatedAt": 1522077420693 }

List Users

As mentioned above, you can use the API to return the list of all the users declared withing an organization. For that purpose, use the API call shown below with the API key of an or account. It supports the and query parameters declared in paging and sorting details.

curl -H 'Authorization: Bearer **API_KEY**''https://CORTEX_APP_URL:9001/api/organization/ORG_ID/user'

and should return a list of users.

If one wants to filter/search for some users (active ones for example), there is a search API to use as below:

curl -XPOST -H 'Authorization: Bearer **API_KEY**' -H 'Content-Type: application/json''https://CORTEX_APP_URL:9001/api/organization/ORG_ID/user/_search' -d '{ "query": {}}'

It also supports the and query parameters declared in paging and sorting details.

List Enabled Analyzers

To list the analyzers that have been enabled within an organization, use the following API call with the API key of an user:

curl -H 'Authorization: Bearer **API_KEY**''https://CORTEX_APP_URL:9001/api/analyzer'

It should return a list of Analyzers.

Please note that this API call does not display analyzers that are disabled. It supports the and query parameters declared in paging and sorting details.

User APIs

The following section describes the APIs that allow creating, updating and listing users within an organization.

User Model

A user is defined by the following attributes:

AttributeDescriptionType
ID/loginreadonly
Namewritable
Roles. Possible values are: , , and writable
Status ( or )writable
organization to which the user belongs (set upon account creation)readonly
Creation datecomputed
User who created the accountcomputed
Last update datecomputed
User who last updated the accountcomputed
true when the user has an API keycomputed
true if the user has a passwordcomputed

List All

This API call allows a to list and search all the users of all defined organizations:

curl -H 'Authorization: Bearer **API_KEY**''https://CORTEX_APP_URL:9001/api/user'

This call supports the and query parameters declared in paging and sorting details.

List Users within an Organization

This call is described in organization APIs.

Search

This API call allows a to perform search on the user accounts created in a Cortex instance:

curl -XPOST -H 'Authorization: Bearer **API_KEY**' -H 'Content-Type: application/json''https://CORTEX_APP_URL:9001/api/user/_search' -d '{ "query": {}}'

This call supports the and query parameters declared in paging and sorting details

Create

This API calls allows you to programmatically create user creation. If the call is made by a user, the request must specify the organization to which the user belong in the field.

If the call is made by an user, the value of field must be the same as the user who makes the call: users are allowed to create users only in their organization.

curl -XPOST -H 'Authorization: Bearer **API_KEY**' -H 'Content-Type: application/json''https://CORTEX_APP_URL:9001/api/user' -d '{ "name": "Demo org Admin", "roles": [ "read", "analyze", "orgadmin" ], "organization": "demo", "login": "demo"}'

If successful, the call returns a JSON object representing the created user as described above.

{ "id": "demo", "organization": "demo", "name": "Demo org Admin", "roles": [ "read", "analyze", "orgadmin" ], "status": "Ok", "createdAt": 1526050123286, "createdBy": "superadmin", "hasKey": false, "hasPassword": false }

Update

This API call allows updating the writable attributed of a user account. It's available to users with or roles. Any user can also use it to update their own information (but obviously not their roles).

curl -XPATCH -H 'Authorization: Bearer **API_KEY**' -H 'Content-Type: application/json''https://CORTEX_APP_URL:9001/api/user/USER_LOGIN' -d '{ "name": "John Doe", "roles": [ "read", "analyze" ], "status": "Locked"}'

It returns a JSON object representing the updated user as described above.

Get Details

This call returns the user details. It's available to users with roles and to users in the same organization. Every user can also use it to read their own details.

curl -H 'Authorization: Bearer **API_KEY**''https://CORTEX_APP_URL:9001/api/user/USER_LOGIN'

It returns a JSON object representing the user as described previously.

Set a Password

This call sets the user's password. It's available to users with or roles. Please note that the request needs to be made using HTTPS with a valid certificate on the server's end to prevent credential sniffing or other PITM (Person-In-The-Middle) attacks.

curl -XPOST -H 'Authorization: Bearer **API_KEY**' -H 'Content-Type: application/json''https://CORTEX_APP_URL:9001/api/user/USER_LOGIN/password/set' -d '{ "password": "SOMEPASSWORD"}'

If successful, the call returns 204 (success / no content).

Change a password

This call allows a given user to change only their own existing password. It is available to all users including and ones. Please note that if a or an needs to update the password of another user, they must use the call described in the previous subsection.

curl -XPOST -H 'Authorization: Bearer **API_KEY**' -H 'Content-Type: application/json''https://CORTEX_APP_URL:9001/api/user/USER_LOGIN/password/change' -d '{ "currentPassword": "password", "password": "new-password"}'

If successful, the call returns 204 (success / no content).

Set and Renew an API Key

This calls allows setting and renewing the API key of a user. It's available to users with or roles. Any user can also use it to renew their own API key. Again, the request needs to be made using HTTPS with a valid certificate on the server's end to prevent credential sniffing or other PITM (Person-In-The-Middle) attacks. You know the drill ;-)

curl -XPOST -H 'Authorization: Bearer **API_KEY**''https://CORTEX_APP_URL:9001/api/user/USER_LOGIN/key/renew'

If successful, it returns the generated API key in a response.

Get an API Key

This calls allows getting a user's API key. It's available to users with or roles. Any user can also use it to obtain their own API key.

curl -H 'Authorization: Bearer **API_KEY**''https://CORTEX_APP_URL:9001/api/user/USER_LOGIN/key'

If successful, the generated API key is returned in response

Revoke an API Key

This calls allow revoking a user's API key. This calls allow revoking a user's API key.

curl -XDELETE -H 'Authorization: Bearer **API_KEY**''https://CORTEX_APP_URL:9001/api/user/USER_LOGIN/key'

A successful request returns nothing (HTTP 200 OK).

Job APIs

The following section describes the APIs that allow manipulating jobs. Jobs are basically submissions made to analyzers and the resulting reports.

Job Model

A job is defined by the following attributes:

AttributeDescriptionType
Job IDcomputed
The organization to which the job belongsreadonly
Analyzer definition namereadonly
Instance ID of the analyzer to which the job is associatedreadonly
Organization to which the user belongs (set upon account creation)readonly
Name of the analyzer to which the job is associatedreadonly
the datatype of the analyzed observablereadonly
Status of the job (, , , , )computed
Value of the analyzed observable (does not apply to observables)readonly
JSON object representing observables (does not apply to non- observables). It defines the, , , and of the observablereadonly
JSON object of key/value pairs set during job creationreadonly
A free text field to set additional text/context for a jobreadonly
The TLP of the analyzed observablereadonly
Start datecomputed
End datecomputed
Creation date. Please note that a job can be requested but not immediately honored. The actual time at which it is started is the value of computed
User who created the jobcomputed
Last update date (only Cortex updates a job when it finishes)computed
User who submitted the job and which identity is used by Cortex to update the job once it is finishedcomputed

List and Search

This call allows a user with , or role to list and search all the analysis jobs made by their organization.

If you want to list all the jobs:

curl -XPOST -H 'Authorization: Bearer **API_KEY**''https://CORTEX_APP_URL:9001/api/job/_search?range=all'

If you want to list 10 jobs:

curl -XPOST -H 'Authorization: Bearer **API_KEY**''https://CORTEX_APP_URL:9001/api/job/_search'

If you want to list 100 jobs:

curl -XPOST -H 'Authorization: Bearer **API_KEY**''https://CORTEX_APP_URL:9001/api/job/_search?range=0-100'

If you want to search jobs according to various criteria:

curl -XPOST -H 'Authorization: Bearer **API_KEY**' -H 'Content-Type: application/json''https://CORTEX_APP_URL:9001/api/job/_search' -d '{ "query": { "_and": [ {"status": "Success"}, {"dataType": "ip"} ] }}'

This call supports the and query parameters declared in paging and sorting details

Get Details

This call allows a user with , or role to get the details of a job. It does not fetch the job report.

curl -H 'Authorization: Bearer **API_KEY**''https://CORTEX_APP_URL:9001/api/job/JOB_ID'

It returns a JSON response with the following structure:

{ "id": "AWNei4vH3rJ8unegCPB9", "analyzerDefinitionId": "Abuse_Finder_2_0", "analyzerId": "220483fde9608c580fb6a2508ff3d2d3", "analyzerName": "Abuse_Finder_2_0", "status": "Success", "data": "8.8.8.8", "parameters": "{}", "tlp": 0, "message": "", "dataType": "ip", "organization": "demo", "startDate": 1526299593923, "endDate": 1526299597064, "date": 1526299593633, "createdAt": 1526299593633, "createdBy": "demo", "updatedAt": 1526299597066, "updatedBy": "demo" }

Get Details and Report

This call allows a user with , or role to get the details of a job including its report.

curl -H 'Authorization: Bearer **API_KEY**''https://CORTEX_APP_URL:9001/api/job/JOB_ID/report'

It returns a JSON response with the structure below. If the job is not yet completed, the field contains a string representing the job status:

{ "id": "AWNei4vH3rJ8unegCPB9", "analyzerDefinitionId": "Abuse_Finder_2_0", "analyzerId": "220483fde9608c580fb6a2508ff3d2d3", "analyzerName": "Abuse_Finder_2_0", "status": "Success", "data": "8.8.8.8", "parameters": "{}", "tlp": 0, "message": "", "dataType": "ip", "organization": "demo", "startDate": 1526299593923, "endDate": 1526299597064, "date": 1526299593633, "createdAt": 1526299593633, "createdBy": "demo", "updatedAt": 1526299597066, "updatedBy": "demo", "report": { "summary": { "taxonomies": [ { "predicate": "Address", "namespace": "Abuse_Finder", "value": "[email protected]", "level": "info" } ] }, "full": { "abuse_finder": { "raw": "...", "abuse": [ "[email protected]" ], "names": [ "Google LLC", "Level 3 Parent, LLC" ], "value": "8.8.8.8" } }, "success": true, "artifacts": [] } }

Wait and Get Job Report

This call is similar the one described above but allows the user to provide a timeout to wait for the report in case it is not available at the time the query was made:

curl -H 'Authorization: Bearer **API_KEY**''https://CORTEX_APP_URL:9001/api/job/JOB_ID/waitreport?atMost=1minute'

The is a duration using the format , or .

Get Artifacts

This call allows a user with , or role to get the extracted artifacts from a job if such extraction has been enabled in the corresponding analyzer configuration. Please note that extraction is imperfect and you might have inconsistent or incorrect data.

curl -H 'Authorization: Bearer **API_KEY**''https://CORTEX_APP_URL:9001/api/job/JOB_ID/artifacts'

It returns a JSON array with the following structure:

[ { "dataType": "ip", "createdBy": "demo", "data": "8.8.8.8", "tlp": 0, "createdAt": 1525432900553, "id": "AWMq4tvLjidKq_asiwcl" } ]

Delete

This API allows a user with or role to delete a job:

curl -XDELETE -H 'Authorization: Bearer **API_KEY**''https://CORTEX_APP_URL:9001/api/job/JOB_ID'

This marks the job as . However the job's data is not removed from the database.

Sours: https://github.com/TheHive-Project/CortexDocs/blob/master/api/api-guide.md
  1. C4 corvette windshield
  2. Spinner flasks
  3. 1366x768 space

Cortex is a hypermedia REST API for e-commerce. What makes Cortex unique is that it uses hypermedia links to associate related resources together rather than relying on resource URLs like most other e-commerce APIs. Much like website links, our hypermedia links allow you to explore the API and discover what resources are needed to build e-commerce features in your application.

Using links, we’ve designed a set of hypermedia controls that enable you to capture selections and data from the shopper. For more information on these controls, see forms, selectors, and needinfo.

Cortex is built following the REST architectural style and uses standard HTTP conventions like HTTP methods to perform actions on resources and HTTP response codes to indicate errors. JSON is returned to describe resource states. Cortex is programming language agnostic and can be used with any programming language that implements an HTTP client.

Cortex is designed to work with a variety of authentication systems and comes bundled with a reference OAuth2 implementation for test purposes.

Studio

Cortex Studio is an API exploration tool that visually renders Cortex hypermedia controls, allowing you to easily explore the API by clicking through links. Cortex Studio comes bundled with Cortex and is available to try at .

Related Links

Cortex Java Software Development Kit (SDK) Documentation

Sours: https://documentation.elasticpath.com/commerce/docs/cortex/
CORTEX - Analyze Observables (IPs, domains, etc.) at Scale! - Build Your Own Intelligence Platform!

Cortex4py

Build statusDiscordLicensePypi page

Cortex4py is a Python API client for Cortex, a powerful observable analysis engine where observables such as IP and email addresses, URLs, domain names, files or hashes can be analyzed one by one using a Web interface.

Cortex4py allows analysts to automate these operations and submit observables in bulk mode through the Cortex REST API from alternative SIRP platforms, custom scripts or MISP.

Cortex4py 2 is compatible with Cortex 2 and does not work with Cortex 1. It can:

  • Manage organizations
  • Manage users
  • Configure analyzers within an organization
  • List and launch analyzers

For more details, please refer to the full documentation.

Note: Cortex4py 2 requires Python 3. It does not support Python 2.

On macOS and Linux, type:

or, if you already have it, update it:

If you are using Python on a Windows operating system, please forgo the command.

Cortex4py is an open source and free software released under the AGPL (Affero General Public License). We, TheHive Project, are committed to ensure that Cortex4py will remain a free and open source project on the long-run.

Information, news and updates are regularly posted on TheHive Project Twitter account and on the blog.

We welcome your contributions. Please feel free to fork the code, play with it, make some patches and send us pull requests using issues.

We do have a Code of conduct. Make sure to check it out before contributing.

Please open an issue on GitHub if you'd like to report a bug or request a feature. We are also available on Discord to help you out.

If you need to contact the project team, send an email to [email protected]

We have set up a Google forum at https://groups.google.com/a/thehive-project.org/d/forum/users. To request access, you need a Google account. You may create one using a Gmail address or without one.

https://thehive-project.org/

Sours: https://github.com/TheHive-Project/Cortex4py

Api cortex

HTTP API

Cortex exposes an HTTP API for pushing and querying time series data, and operating the cluster itself.

For the sake of clarity, in this document we have grouped API endpoints by service, but keep in mind that they’re exposed both when running Cortex in microservices and singly-binary mode:

  • Microservices: each service exposes its own endpoints
  • Single-binary: the Cortex process exposes all API endpoints for the services running internally

Endpoints

APIServiceEndpoint
Index pageAll services
ConfigurationAll services
Runtime ConfigurationAll services
Services statusAll services
Readiness probeAll services
MetricsAll services
PprofAll services
FgprofAll services
Remote writeDistributor
Tenants statsDistributor
HA tracker statusDistributor
Flush chunks / blocksIngester
ShutdownIngester
Ingesters ring statusIngester
Instant queryQuerier, Query-frontend
Range queryQuerier, Query-frontend
Exemplar queryQuerier, Query-frontend
Get series by label matchersQuerier, Query-frontend
Get label namesQuerier, Query-frontend
Get label valuesQuerier, Query-frontend
Get metric metadataQuerier, Query-frontend
Remote readQuerier, Query-frontend
Get tenant ingestion statsQuerier
Get tenant chunksQuerier
Ruler ring statusRuler
Ruler rulesRuler
List rulesRuler
List alertsRuler
List rule groupsRuler
Get rule groups by namespaceRuler
Get rule groupRuler
Set rule groupRuler
Delete rule groupRuler
Delete namespaceRuler
Delete tenant configurationRuler
Alertmanager statusAlertmanager
Alertmanager configsAlertmanager
Alertmanager ring statusAlertmanager
Alertmanager UIAlertmanager
Alertmanager Delete Tenant ConfigurationAlertmanager
Get Alertmanager configurationAlertmanager
Set Alertmanager configurationAlertmanager
Delete Alertmanager configurationAlertmanager
Delete seriesPurger
List delete requestsPurger
Cancel delete requestPurger
Tenant delete requestPurger
Tenant delete statusPurger
Store-gateway ring statusStore-gateway
Compactor ring statusCompactor
Get rule filesConfigs API (deprecated)
Set rule filesConfigs API (deprecated)
Get template filesConfigs API (deprecated)
Set template filesConfigs API (deprecated)
Get Alertmanager config fileConfigs API (deprecated)
Set Alertmanager config fileConfigs API (deprecated)
Validate Alertmanager configConfigs API (deprecated)
Deactivate configsConfigs API (deprecated)
Restore configsConfigs API (deprecated)

Path prefixes

In this documentation you will find the usage of some placeholders for the path prefixes, whenever the prefix is configurable. The following table shows the supported prefixes.

PrefixDefaultCLI FlagYAML Config

Authentication

When multi-tenancy is enabled, endpoints requiring authentication are expected to be called with the HTTP request header set to the tenant ID. Otherwise, when multi-tenancy is disabled, Cortex doesn’t require any request to have the header.

Multi-tenancy can be enabled/disabled via the CLI flag or its respective YAML config option.

For more information, please refer to the dedicated Authentication and Authorisation guide.

All services

The following API endpoints are exposed by all services.

Index page

Displays an index page with links to other web pages exposed by Cortex.

Configuration

Displays the configuration currently applied to Cortex (in YAML format), including default values and settings via CLI flags. Sensitive data is masked. Please be aware that the exported configuration doesn’t include the per-tenant overrides.

Different modes

Displays the configuration currently applied to Cortex (in YAML format) as before, but containing only the values that differ from the default values.

Displays the configuration using only the default values.

Runtime Configuration

Displays the runtime configuration currently applied to Cortex (in YAML format), including default values. Please be aware that the endpoint will be only available if Cortex is configured with the option.

Different modes

Displays the runtime configuration currently applied to Cortex (in YAML format) as before, but containing only the values that differ from the default values.

Services status

Displays a web page with the status of internal Cortex services.

Readiness probe

Returns 200 when Cortex is ready to serve traffic.

Metrics

Returns the metrics for the running Cortex service in the Prometheus exposition format.

Pprof

Returns the runtime profiling data in the format expected by the pprof visualization tool. There are many things which can be profiled using this including heap, trace, goroutine, etc.

For more information, please check out the official documentation of pprof.

Fgprof

Returns the sampling Go profiling data which allows you to analyze On-CPU as well as Off-CPU (e.g. I/O) time together.

For more information, please check out the official documentation of fgprof.

Distributor

Remote write

Entrypoint for the Prometheus remote write.

This API endpoint accepts an HTTP POST request with a body containing a request encoded with Protocol Buffers and compressed with Snappy. The definition of the protobuf message can be found in . The HTTP request should contain the header set to .

For more information, please check out Prometheus Remote storage integrations.

Requires authentication.

Distributor ring status

Displays a web page with the distributor hash ring status, including the state, healthy and last heartbeat time of each distributor.

Tenants stats

Displays a web page with per-tenant statistics updated in realtime, including the total number of active series across all ingesters and the current ingestion rate (samples / sec).

HA tracker status

Displays a web page with the current status of the HA tracker, including the elected replica for each Prometheus HA cluster.

Ingester

Flush chunks / blocks

Triggers a flush of the in-memory time series data (chunks or blocks) to the long-term storage. This endpoint triggers the flush also when or are disabled.

When using blocks storage, this endpoint accepts parameter to specify tenant whose blocks are compacted and shipped. This parameter may be specified multiple times to select more tenants. If no tenant is specified, all tenants are flushed.

Flush endpoint now also accepts parameter, which makes the call synchronous – it will only return after flushing has finished. Note that returned status code does not reflect the result of flush operation. This parameter is only available when using blocks storage.

Shutdown

Flushes in-memory time series data from ingester to the long-term storage, and shuts down the ingester service. Notice that the other Cortex services are still running, and the operator (or any automation) is expected to terminate the process with a / signal after the shutdown endpoint returns. In the meantime, will not return 200. This endpoint will unregister the ingester from the ring even if is disabled.

This API endpoint is usually used by scale down automations.

Ingesters ring status

Displays a web page with the ingesters hash ring status, including the state, healthy and last heartbeat time of each ingester.

Querier / Query-frontend

The following endpoints are exposed both by the querier and query-frontend.

Instant query

Prometheus-compatible instant query endpoint.

For more information, please check out the Prometheus instant query documentation.

Requires authentication.

Range query

Prometheus-compatible range query endpoint. When the request is sent through the query-frontend, the query will be accelerated by query-frontend (results caching and execution parallelisation).

For more information, please check out the Prometheus range query documentation.

Requires authentication.

Exemplar query

Prometheus-compatible exemplar query endpoint.

For more information, please check out the Prometheus exemplar query documentation.

Requires authentication.

Get series by label matchers

Find series by label matchers. Differently than Prometheus and due to scalability and performances reasons, Cortex currently ignores the and request parameters and always fetches the series from in-memory data stored in the ingesters. There is experimental support to query the long-term store with the blocks storage engine when is set.

For more information, please check out the Prometheus series endpoint documentation.

Requires authentication.

Get label names

Get label names of ingested series. Differently than Prometheus and due to scalability and performances reasons, Cortex currently ignores the and request parameters and always fetches the label names from in-memory data stored in the ingesters. There is experimental support to query the long-term store with the blocks storage engine when is set.

For more information, please check out the Prometheus get label names documentation.

Requires authentication.

Get label values

Get label values for a given label name. Differently than Prometheus and due to scalability and performances reasons, Cortex currently ignores the and request parameters and always fetches the label values from in-memory data stored in the ingesters. There is experimental support to query the long-term store with the blocks storage engine when is set.

For more information, please check out the Prometheus get label values documentation.

Requires authentication.

Get metric metadata

Prometheus-compatible metric metadata endpoint.

For more information, please check out the Prometheus metric metadata documentation.

Requires authentication.

Remote read

Prometheus-compatible remote read endpoint.

For more information, please check out Prometheus Remote storage integrations.

Requires authentication.

Querier

Get tenant ingestion stats

Returns realtime ingestion rate, for the authenticated tenant, in format.

Requires authentication.

Get tenant chunks

Fetch a compressed tar of all the chunks containing samples for the given time range and label matchers. This endpoint is supported only by the chunks storage, requires and should not be exposed to users but just used for debugging purposes.

URL query parameterDescription
Start timestamp, in RFC3339 format or unix epoch.
End timestamp, in RFC3339 format or unix epoch.
Label matcher that selects the series for which chunks should be fetched.

Requires authentication.

Ruler

The ruler API endpoints require to configure a backend object storage to store the recording rules and alerts. The ruler API uses the concept of a “namespace” when creating rule groups. This is a stand in for the name of the rule file in Prometheus and rule groups must be named uniquely within a namespace.

Ruler ring status

Displays a web page with the ruler hash ring status, including the state, healthy and last heartbeat time of each ruler.

Ruler rules

List all tenant rules. This endpoint is not part of ruler-API and is always available regardless of whether ruler-API is enabled or not. It should not be exposed to end users. This endpoint returns a YAML dictionary with all the rule groups for each tenant and status code on success.

List rules

Prometheus-compatible rules endpoint to list alerting and recording rules that are currently loaded.

For more information, please check out the Prometheus rules documentation.

This experimental endpoint is disabled by default and can be enabled via the CLI flag (or its respective YAML config option).

Requires authentication.

List alerts

Prometheus-compatible rules endpoint to list of all active alerts.

For more information, please check out the Prometheus alerts documentation.

This experimental endpoint is disabled by default and can be enabled via the CLI flag (or its respective YAML config option).

Requires authentication.

List rule groups

List all rules configured for the authenticated tenant. This endpoint returns a YAML dictionary with all the rule groups for each namespace and status code on success.

This experimental endpoint is disabled by default and can be enabled via the CLI flag (or its respective YAML config option).

Requires authentication.

Example response

Get rule groups by namespace

Returns the rule groups defined for a given namespace.

This experimental endpoint is disabled by default and can be enabled via the CLI flag (or its respective YAML config option).

Requires authentication.

Example response

Get rule group

Returns the rule group matching the request namespace and group name.

This experimental endpoint is disabled by default and can be enabled via the CLI flag (or its respective YAML config option).

Requires authentication.

Set rule group

Creates or updates a rule group. This endpoint expects a request with header and the rules YAML definition in the request body, and returns on success.

This experimental endpoint is disabled by default and can be enabled via the CLI flag (or its respective YAML config option).

Requires authentication.

Example request

Request headers:

    Request body:

    Delete rule group

    Deletes a rule group by namespace and group name. This endpoints returns on success.

    This experimental endpoint is disabled by default and can be enabled via the CLI flag (or its respective YAML config option).

    Requires authentication.

    Delete namespace

    Deletes all the rule groups in a namespace (including the namespace itself). This endpoint returns on success.

    This experimental endpoint is disabled by default and can be enabled via the CLI flag (or its respective YAML config option).

    Requires authentication.

    Delete tenant configuration

    This deletes all rule groups for tenant, and returns on success. Calling endpoint when no rule groups exist for user returns . Authentication is only to identify the tenant.

    This is intended as internal API, and not to be exposed to users. This endpoint is enabled regardless of whether is enabled or not.

    Requires authentication.

    Alertmanager

    Alertmanager status

    Displays a web page with the current status of the Alertmanager, including the Alertmanager cluster members.

    Alertmanager configs

    List all Alertmanager configurations. This endpoint is not part of alertmanager-API and is always available regardless of whether alertmanager-API is enabled or not. It should not be exposed to end users. This endpoint returns a YAML dictionary with all the Alertmanager configurations and status code on success.

    Alertmanager ring status

    Displays a web page with the Alertmanager hash ring status, including the state, healthy and last heartbeat time of each Alertmanager instance.

    Alertmanager UI

    Displays the Alertmanager UI.

    Requires authentication.

    Alertmanager Delete Tenant Configuration

    This endpoint deletes configuration for a tenant identified by header. It is internal, available even if Alertmanager API is not enabled by using . The endpoint returns a status code of if the user’s configuration has been deleted, or it didn’t exist in the first place.

    Requires authentication.

    Get Alertmanager configuration

    Get the current Alertmanager configuration for the authenticated tenant, reading it from the configured object storage.

    This endpoint doesn’t accept any URL query parameter and returns on success.

    This experimental endpoint is disabled by default and can be enabled via the CLI flag (or its respective YAML config option).

    Requires authentication.

    Set Alertmanager configuration

    Stores or updates the Alertmanager configuration for the authenticated tenant. The Alertmanager configuration is stored in the configured backend object storage.

    This endpoint expects the Alertmanager YAML configuration in the request body and returns on success.

    This experimental endpoint is disabled by default and can be enabled via the CLI flag (or its respective YAML config option).

    Requires authentication.

    Note: When using send the request body from a file, ensure that you use the flag instead of , , or . The latter options do not preserve carriage returns and newlines.

    Example request body

    Delete Alertmanager configuration

    Deletes the Alertmanager configuration for the authenticated tenant.

    This endpoint doesn’t accept any URL query parameter and returns on success.

    This experimental endpoint is disabled by default and can be enabled via the CLI flag (or its respective YAML config option).

    Requires authentication.

    Purger

    The Purger service provides APIs for requesting deletion of series in chunks storage and managing delete requests. For more information about it, please read the Delete series Guide.

    Delete series

    Prometheus-compatible delete series endpoint.

    For more information, please check out the Prometheus delete series documentation.

    Requires authentication.

    List delete requests

    List all the delete requests.

    Requires authentication.

    Cancel delete request

    Cancel a delete request while the request is still in the grace period (before the request is effectively processed by the purger and time series data is hard-deleted from the storage).

    URL query parameterDescription
    Deletion request ID to cancel. Can be obtained by the List delete requests endpoint.

    Requires authentication.

    Tenant Delete Request

    Request deletion of ALL tenant data. Only works with blocks storage. Experimental.

    Requires authentication.

    Tenant Delete Status

    Returns status of tenant deletion. Output format to be defined. Experimental.

    Requires authentication.

    Store-gateway

    Store-gateway ring status

    Displays a web page with the store-gateway hash ring status, including the state, healthy and last heartbeat time of each store-gateway.

    Compactor

    Compactor ring status

    Displays a web page with the compactor hash ring status, including the state, healthy and last heartbeat time of each compactor.

    Configs API

    This service has been deprecated in favour of Ruler and Alertmanager API.

    The configs API service provides an API-driven multi-tenant approach to handling various configuration files for Prometheus. The service hosts an API where users can read and write Prometheus rule files, Alertmanager configuration files, and Alertmanager templates to a database. Each tenant will have its own set of rule files, Alertmanager config, and templates.

    Request / response schema

    The following schema is used both when retrieving the current configs from the API and when setting new configs via the API:


    • Should be incremented every time data is updated; Cortex will use the config with the highest number.

    • Allows compatibility for tenants with config in Prometheus V1 format. Pass “1” or “2” according to which Prometheus version you want to match.

    • The contents of the alertmanager config file should be as described here, encoded as a single string to fit within the overall JSON payload.

    • The contents of a rules file should be as described here, encoded as a single string to fit within the overall JSON payload.

    • The contents of a template file should be as described here, encoded as a single string to fit within the overall JSON payload. These entries should match the entries in . Example:

    Get rule files

    Get the current rule files for the authenticated tenant.

    Requires authentication.

    Set rule files

    Replace the current rule files for the authenticated tenant.

    Requires authentication.

    Get template files

    Get the current template files for the authenticated tenant.

    Requires authentication.

    Set template files

    Replace the current template files for the authenticated tenant.

    Requires authentication.

    Get Alertmanager config file

    Get the current Alertmanager config for the authenticated tenant.

    Requires authentication.

    Set Alertmanager config file

    Replace the current Alertmanager config for the authenticated tenant.

    Requires authentication.

    Validate Alertmanager config file

    Validate the Alertmanager config in the request body. The request body is expected to contain only the Alertmanager YAML config.

    Deactivate configs

    Disable configs for the authenticated tenant. Please be aware that setting a new config will effectively “re-enable” the Rules and Alertmanager configuration for the tenant.

    Requires authentication.

    Restore configs

    Re-enable configs for the authenticated tenant, after being previously deactivated.

    Requires authentication.

    Sours: https://cortexmetrics.io/docs/api/
    CORTEX - Analyze Observables (IPs, domains, etc.) at Scale! - Build Your Own Intelligence Platform!

    .

    You will also like:

    .



    576 577 578 579 580