Skip to main content
Version: 5.0

api

Description

Makes requests to external APIs.

Syntax

api [<connection>] [<query>] [<url>] [<method>] [<verify>] [<ssl>] [<ssl_type>] [<cert>] [<auth>] [<auth_type>] [<params>] [<headers>] [<timeout>] [<body>] [<body_type>]

Optional Arguments

ParameterSyntaxDescription
connectionconnection=<string>Name of a predefined api connection.
queryquery=<string>Name of a predefined api query.
urlurl=<string>See URL Processing.
method<string>HTTP request method, defaults to GET.
verifyverify=<boolean>When true, enables hostname verification.
sslssl=<boolean>When true, enables ssl validation.
ssl_typessl_type=<string>ssl protocol type. Valid values: ssl2.3, ssl3, tls, tls1.1, tls1.2, tls1.3.
certcert=<string>Path to certificate when using ssl.
authauth=<string>Authorization token.
auth_typeauth_type=<string>Authorization type. Valid values: basic, apiKey, bearer.
paramsparams=<string>Request parameters.
headersheaders=<string>Request headers.
timeouttimeout=<int>Request timeout.
bodybody=<string>Request body.
body_typebody_type=<string>body type. Valid values: json, xml, javascript, html, text, binary.
warning

The command requires either a url definition in the connection or a url argument to be specified.

info

When using both api connection or query and optional parameters, the optional parameters take precedence.

URL Processing

The final URL is constructed by processing URLs from connection and query arguments. If query contains a full URL, it's used as-is. For relative URLs, only the host value is taken from connection and combined with the path from query

url argument

If the url argument is provided. Its value overrides the URL from query. The same processing rules apply: full URLs are used as-is, while relative paths are combined with the host from connection.

Tokenization of params and headers

When using params and headers arguments, you can utilize tokens from the keystore.

info

Tokens for headers must be stored in the keystore under the path sme.sa.api.header.<token_name>, while tokens for params should be stored under sme.sa.api.param.<token_name>. Replace <token_name> with your actual token name, e.g., my_authorization.

Creating a token

To create a token of type header named my_authorization, make a request to the keystore. The value field should contain the actual value that will replace the token in requests.

POST _core/keystore/sme.sa.api.header.my_authorization
{
"value": "Basic "
}

Using tokens

To use tokens in the api command within search queries, specify the token name in double curly braces.

| api connection=my-connection headers="Authorization={{my_authorization}}"

Request Examples

Example 1

Queries the api specified in the url parameter and returns documents containing user information.

| api url="https://jsonplaceholder.typicode.com/users" 

Example 2

The json connection contains the base URL https://jsonplaceholder.typicode.com/, which is combined with the resource path from the url parameter.

| api connection=json url="/todos"

Example 3

Executes a request using predefined api connection and query.

| api connection=my-connection query=my-query

Example 4

Executes a request using predefined api connection and query, but with ssl validation disabled.

| api connection=my-connection query=my-query ssl=false