v4

Client

View as markdown

Create and configure the client, and read the metadata of every API response.

Client is the synchronous client and AsyncClient is its counterpart for asyncio and Trio. Both take the same arguments and have the same methods, and every AsyncClient method is a coroutine. A Client pools connections and is safe to share across threads, so create one and reuse it for every request. Use one AsyncClient per event loop.

Constructor

Every argument after api_key is keyword-only.

Constructor

def __init__(
    self,
    api_key: str | None = None,
    *,
    base_url: str = DEFAULT_BASE_URL,
    max_retries: int = DEFAULT_MAX_RETRIES,
    timeout: float | httpx.Timeout | None = DEFAULT_TIMEOUT,
    http_client: httpx.Client | None = None,
    user_agent: str | None = None,
    response_hook: ResponseHook | None = None,
) -> None

import synthient

client = synthient.Client(max_retries=4, user_agent="my-app/1.0")
  • Network: Creating a client sends no request.
  • Input: A missing API key, a key that is not printable ASCII, or an invalid argument raises ValueError. An API key that is not a string raises TypeError.

Arguments

  • Name
    api_key
    Type
    str | None
    Description

    The API key. None reads the SYNTHIENT_API_KEY environment variable. Surrounding whitespace is trimmed, and an empty key raises ValueError. A key that is not a string raises TypeError.

  • Name
    base_url
    Type
    str
    Description

    The API base URL, including the version path. The default is DEFAULT_BASE_URL. It must be an http or https URL with a host and no query or fragment, and a trailing slash is removed.

  • Name
    max_retries
    Type
    int
    Description

    How many times a failed request is retried. The default is 2, and 0 disables retries. A negative or non-integer value raises ValueError. See Retries and timeouts.

  • Name
    timeout
    Type
    float | httpx.Timeout | None
    Description

    The httpx timeout for every request. The default, httpx.Timeout(60.0, connect=10.0), waits up to 10 seconds to connect and 60 seconds for each read or write, which also suits streams because the API sends a keepalive line every 15 seconds. A number sets every phase, and None disables the timeout. Negative, non-finite, and non-numeric values raise ValueError.

  • Name
    http_client
    Type
    httpx.Client | None
    Description

    An httpx client to send requests with, for proxies, TLS, or transports. On AsyncClient it is an httpx.AsyncClient. The SDK never closes or modifies it. API redirects are not followed, and the SDK's timeout applies to every request it sends. Storage requests exclude its default headers, cookies, query parameters, and authentication to protect credentials and presigned URLs.

  • Name
    user_agent
    Type
    str | None
    Description

    Appended to the User-Agent header, such as "my-app/1.2". The header starts with synthient-python/ followed by the SDK version.

  • Name
    response_hook
    Type
    ResponseHook | None
    Description

    Called with the ResponseMetadata of every API response. See Response metadata.

Closing

Closes the connection pool.

def close(self) -> None

async def aclose(self) -> None
  • Cleanup: A with block on Client, or an async with block on AsyncClient, closes the client on exit. A client never closes an http_client you passed in.
  • Repeat calls: Calling it again does nothing.
  • Errors: Requests on a closed client raise RuntimeError.

AsyncClient

The async client is used the same way, with await on every method:

import asyncio

import synthient


async def main() -> None:
    async with synthient.AsyncClient() as client:
        info = await client.lookup_ip("8.8.8.8")

    if info.intelligence is not None:
        print(info.intelligence.risk_score, info.intelligence.categories)


asyncio.run(main())

Feed streams and downloads are async context managers, entered with async with. Events from a stream and exports from iter_exports are read with async for, and a download's body with aiter_bytes(). The Feeds page shows each one.

Constants

  • Name
    DEFAULT_BASE_URL
    Type
    str
    Description

    "https://api.synthient.com/api/v4", the base URL of the Synthient HTTP API.

  • Name
    __version__
    Type
    str
    Description

    The SDK version, such as "1.0.0". It is sent in the User-Agent header.

Response metadata

The response_hook argument is called synchronously with a ResponseMetadata after each API response's headers arrive.

import synthient


def log_response(meta: synthient.ResponseMetadata) -> None:
    print(meta.status_code, meta.request_id, meta.headers.get("ratelimit-remaining"))


client = synthient.Client(response_hook=log_response)
  • Coverage: The hook sees retries, pages, stream handshakes, and errors. Storage download responses are excluded.
  • Async: The hook is a plain function on AsyncClient too.
  • Errors: An exception the hook raises propagates to the caller.
  • Concurrency: A client shared across threads calls it from each of those threads.

ResponseHook

ResponseHook = Callable[[ResponseMetadata], None]

ResponseMetadata

A frozen dataclass describing one HTTP response from the Synthient API.

  • Name
    status_code
    Type
    int
    Description

    The HTTP status code of the response.

  • Name
    request_id
    Type
    str
    Description

    The X-Request-Id header, or "".

  • Name
    headers
    Type
    httpx.Headers
    Description

    A copy of the response headers, so changing it does not affect the client. Headers can contain sensitive data, such as presigned download URLs.

There is no rate limit type. Read the RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers from headers when they are present. Limits are shared by every key of a team. See Rate Limits.

Previous
Next