The per-resource pages are generated from the operation manifest that ships in the SDK packages.
Client structure
One namespace per resource — not per generated service — with the verb as the method name:client.agents.create(...), not
client.agents.agent_create_agent(...). A resource can nest: client.agents
has a sessions and a traces sub-resource, reached as
client.agents.sessions.list(agent_id).
snake_case in Python, camelCase in
TypeScript. The per-resource reference marks the exceptions: skills.create
and skills.bulk_create upload as multipart forms, the API proxy methods take
no body, and users.traces.delete_content takes its workspace ID from the
client’s workspace, so set one. Operations that upload an image or file take
raw bytes (Blob in TypeScript) as the body.
with_workspace() selects another default workspace using the same credentials
and connections. It does not switch organizations or grant workspace access:
Resources you reach most
Content operations (file bytes, skill bundles) return the stored media type,
not JSON — check the content type before parsing or you will write a corrupt
file.
Prefer the tracing SDK over building session records by hand.
Use
sessions/agents.sessions directly only when the runtime cannot be
instrumented.
Errors
Every error the gateway returns is normalised to a singleAtlanAPIError
carrying its problem document, in place of the generated per-status exception
classes, so you handle a status and a stable code rather than parsing bodies:
status, code, title, detail, and the request’s
trace_id / traceId — quote that trace ID when reporting a gateway problem.
detail is deliberately kept out of the exception message so an error that
reaches a log or a user-facing surface cannot carry a server-supplied string.
A bulk write in which every item was refused is raised with code
bulk_all_rejected, and its slot_errors (slotErrors in TypeScript) keep
each refused item’s own status, code, and detail in submission order — a
BulkSlotError with index, status, code, and detail — so you can tell
why each item was refused; for eval results, a duplicate case_id
(duplicate_case_id) against an experiment already finished (conflict).
Each slot’s detail is server text, so it reaches no exception message either.
Catch AtlanAPIError and branch on status or code. You never need to catch
a per-status exception class. Arguments the generated client rejects before
sending, such as a missing required parameter, raise its own
validation error instead: pydantic.ValidationError in Python and
RequiredError in TypeScript.
Writes are not retried automatically. A retried create can duplicate an
artifact, so retry deliberately — see
Errors and retries.
Requests make one attempt by default. In TypeScript, pass createRetryMiddleware
to the client to opt in to bounded retries:
GET, HEAD, and OPTIONS on 408, 429, 500,
502, 503, and 504, and on network failures — up to maxAttempts attempts
including the first (default 3, at most 10). Any other status comes back
untouched. Between attempts it waits a random delay under a ceiling that starts
at baseDelayMs (default 250 ms), doubles each attempt, and stops at
maxDelayMs (default 10 seconds). It never retries sooner than Retry-After
when the response includes one, and a Retry-After longer than maxDelayMs
stops the retries. A write is retried only when you add its method to
methods, and a streamed body is never replayed — include a write only when
repeating it is safe. A request that times out is not retried, and an abort
during the wait cancels the request instead of sending another attempt.
Reuse the client’s transport
In TypeScript, the SDK exports the request transport the management client runs on, so calls your application makes to the Gateway outside the client can share its timeout, cancellation, and failure kinds:createGatewayFetch takes three optional settings:
Each call makes one attempt and forwards the caller’s abort signal, including
one attached to a
Request. The transport holds no credential and never
retries: your own calls carry their own authentication.
validateGatewayOrigin trims surrounding whitespace and trailing slashes, and
throws unless the origin is an absolute http: or https: URL with a host
and no embedded credentials, query, or fragment.
The client runs on the same pieces: it validates gatewayOrigin when you
construct it and sends its API requests through createGatewayFetch with your
fetch option. It does not hand timeoutMs to that transport; the client
applies timeoutMs as one deadline for each whole operation, covering token
lookup, retries, and reading the response body. Uploads
to a presigned URL go through a second createGatewayFetch that does take
timeoutMs. In both, the client’s mapError turns a cancellation into a
cancellation error and other failures into AtlanAPIError connection errors;
a cause that is already an AtlanAPIError passes through unchanged.
Find omitted operations
Start with the per-resource reference: together those pages list all 316. Beyond that, the operation manifest ships inside both packages and is the canonical inventory, so you can enumerate the surface at runtime:client.raw.<service>.apis,
keyed by the contract’s service name (agent, skill, file, mcp, model,
api, otel, registry, secret, eval, repo) rather than by resource, when
you want a generated signature rather than the facade’s forwarded call.
In TypeScript, the generated APIs are typed by service and tag:
client.raw.registry.apis.releases is the generated ReleasesApi, and its
calls keep the generated request and response types, middleware included:
See also
- Agents cookbook: register an agent, attach tools and files, record a run.
- Publish and retrieve skills through API: publish, retrieve, and inspect skills.
- Trace agent runs: spans, cost, scores, and visitor identity.
- HTTP API: the underlying HTTP contract.