Client setup

Construct and configure the synchronous Rank and asynchronous AsyncRank clients, including auth, timeouts, retries and custom headers.

Everything in the SDK starts from a client. There are two: rank.Rank for synchronous code and rank.AsyncRank for asyncio. They expose the same resources and accept the same constructor arguments — the async client simply returns awaitables.

Rank vs. AsyncRank

Pick the client that matches your runtime. Resource methods, parameters and return types are identical; only the call style differs.

import rank

client = rank.Rank(api_key="rk_live_xxxxxxxxxxxxxxxx")

pentests = client.pentests.list()
for p in pentests.items:
    print(p.name, p.status)

import asyncio
import rank

async def main():
    client = rank.AsyncRank(api_key="rk_live_xxxxxxxxxxxxxxxx")

    pentests = await client.pentests.list()
    for p in pentests.items:
        print(p.name, p.status)

    await client.close()

asyncio.run(main())

Constructor options

Both clients take the same keyword-only arguments:

import rank

client = rank.Rank(
    api_key="rk_live_xxxxxxxxxxxxxxxx",
    base_url="https://api.aleex-rank.ai",
    agent_base_url="https://aleex.aleex-rank.ai",
    timeout=60.0,
    max_retries=2,
    custom_headers={"X-Request-Source": "ci-pipeline"},
)

Authentication

Rank authenticates every request with an API key sent in the X-API-Key header. You can provide the key in two ways:

import rank

# Explicit argument
client = rank.Rank(api_key="rk_live_xxxxxxxxxxxxxxxx")

# Or read RANK_API_KEY from the environment
#   export RANK_API_KEY=rk_live_xxxxxxxxxxxxxxxx
client = rank.Rank()

If no key is found — neither passed nor present in RANK_API_KEY — the constructor raises a ValueError immediately, before any request is made. API keys are created from the Rank dashboard; see Authentication for the full walkthrough.

Environment variables

Explicit constructor arguments always take precedence over environment variables.

Timeouts and retries

timeout bounds each individual request, and max_retries controls how many times the client retries transient failures (connection errors, timeouts and 5xx responses). Validation errors and other 4xx responses are not retried — they are raised immediately as typed exceptions.

import rank

# A patient client for long pentest operations, with more aggressive retries
client = rank.Rank(timeout=120.0, max_retries=4)

Some long-running calls accept a per-call timeout that overrides the client default. For example, client.pentests.process_vulnerabilities(...) defaults to a 600-second timeout because the AI analyses every recorded response.

Custom headers

Use custom_headers to tag traffic from a specific environment or to satisfy a gateway in front of your deployment. These headers are merged into every request to both the PHP and Go backends.

import rank

client = rank.Rank(
    custom_headers={
        "X-Request-Source": "ci-pipeline",
        "X-Environment": "staging",
    },
)

Closing clients

Each client holds pooled HTTP connections to both backends. Close them when you are done to release the sockets. The cleanest approach is the context-manager form, which closes automatically on exit.

import rank

# Automatic cleanup
with rank.Rank() as client:
    client.pentests.list()

# Manual cleanup for a long-lived client
client = rank.Rank()
try:
    client.pentests.list()
finally:
    client.close()

import rank

# Automatic cleanup
async with rank.AsyncRank() as client:
    await client.pentests.list()

# Manual cleanup for a long-lived client
client = rank.AsyncRank()
try:
    await client.pentests.list()
finally:
    await client.close()

With a client configured, continue to the Resources tour or jump straight to Streaming.