{"schema_version":"1.0","publisher":"Primitive SDKs","canonical_url":"https://test.abhinandan.one/python-generated-api-client","markdown_url":"https://test.abhinandan.one/python-generated-api-client.md","article":{"id":"aca856b3-5de3-4339-8745-a84689c33357","article_slug":"python-generated-api-client","parent_article_slug":null,"parent_article_title":null,"kind":"guide","published_at":"2026-08-11T18:55:07.224377+00:00","keywords":["primitive.api","create_client","primitive.api.models","sync detailed","semantic_search","Primitive Memories Python"],"meta_description":"Call primitive.api's generated operation functions directly to reach account, memories, and semantic-search endpoints not covered by the high-level Python client.","og_image_url":null,"source_file_paths":["sdk-python/src/primitive/client.py","sdk-python/README.md","sdk-go/README.md"],"recording_id":null,"replayable":false,"task_name":"Generated API Client (Python)","category":"Python SDK","summary":null,"description":"Call any Primitive REST operation directly through primitive.api, the generated HTTP client, for account, memories, and semantic-search operations that the high-level PrimitiveClient doesn't wrap.","content_kind":"repo_page","content_markdown":"Reach for the generated API module, `primitive.api`, when you need an operation the high-level [`PrimitiveClient`](python-sdk-quickstart) doesn't wrap directly: account details, Primitive Memories reads and writes, or semantic search. `primitive.api` is generated from the same [OpenAPI spec](monorepo-and-releases) that produces the Node and Go clients, so every operation the API exposes has a matching Python function.\n\nThe high-level client (`client.send`, `client.reply`, `client.forward`) stays the default for outbound/inbound mail, see [Sending Email](python-send-email) and [Receiving and Parsing Inbound Email](python-receive-email). Use `primitive.api` for everything else.\n\n<Note>\n\n`primitive.api` is generated by `sdk-python/scripts/generate_api_client.py`, which runs `openapi-python-client` against the normalized `openapi/primitive-api.codegen.json` spec and copies the output into `src/primitive/api/`. You never hand-edit files under this path.\n\n</Note>\n\n## Construct a client\n\nEvery generated operation function takes a `client` keyword argument built with `create_client`.\n\n```python\nfrom primitive.api import create_client\n\nclient = create_client(\"prim_test\")\n```\n\n`create_client` accepts the same API key format as the high-level `primitive.client(...)` (`prim_test` in examples, or `os.environ[\"PRIMITIVE_API_KEY\"]` in real code). It targets the primary API host; the generated client does not need the dual-host split the high-level client uses internally for `/send-mail` and `/emails/{id}/reply`, because those two endpoints have dedicated high-level methods.\n\n## Call a generated operation\n\n<Steps>\n\n<Step title=\"Import the operation function\">\n\nEach OpenAPI operation lives at a predictable import path: `primitive.api.api.<tag>.<operation_name>`. Import the `sync` variant for a blocking call (an `asyncio` variant exists alongside it for async code):\n\n```python\nfrom primitive.api.api.account.get_account import sync as get_account\n```\n\n</Step>\n\n<Step title=\"Call it with the client\">\n\n```python\naccount = get_account(client=client)\nprint(account)\n```\n\nThe `sync` variant returns the parsed response model for the operation, or `None` when the response could not be parsed into a model. Reach for `sync_detailed` when you need the status code and headers as well.\n\n</Step>\n\n<Step title=\"Handle request bodies with typed model classes\">\n\nOperations that take a body import a matching model from `primitive.api.models` and construct it before passing it as `body`:\n\n```python\nfrom primitive.api.api.memories.set_memory import sync as set_memory\nfrom primitive.api.models.set_memory_input import SetMemoryInput\n\nsaved = set_memory(\n    client=client,\n    body=SetMemoryInput(key=\"greeting\", value=\"hello\"),\n)\n```\n\n</Step>\n\n</Steps>\n\n## Primitive Memories\n\n[Primitive Memories](node-sdk-api-client) are durable JSON key-value records, available here as the generated `set_memory` / `get_memory` / `search_memories` / `delete_memory` operations. Calls default to org scope.\n\n```python\nfrom primitive.api import create_client\nfrom primitive.api.api.memories.get_memory import sync as get_memory\nfrom primitive.api.api.memories.set_memory import sync as set_memory\nfrom primitive.api.models.set_memory_input import SetMemoryInput\n\nclient = create_client(\"prim_test\")\n\nsaved = set_memory(\n    client=client,\n    body=SetMemoryInput(key=\"greeting\", value=\"hello\"),\n)\nmemory = get_memory(client=client, key=\"greeting\")\n```\n\nFunction scope is available on the generated memory operations with `scope_type=\"function\"` and `scope_id=<function-id>`; the id is the function's UUID, not the function name.\n\n```python\nmemory = get_memory(\n    client=client,\n    key=\"state\",\n    scope_type=\"function\",\n    scope_id=\"3fa85f64-5717-4562-b3fc-2c963f66afa6\",\n)\n```\n\n<Tip>\n\n`search_memories` lists records by key prefix, it is not free-text or semantic search. For ranked search across mail, use the generated `semantic_search` operation shown below (or `primitive semantic-search` from the CLI).\n\n</Tip>\n\n## Semantic search\n\nThe generated `semantic_search` operation runs ranked semantic, hybrid, or keyword search across received and sent mail:\n\n```python\nfrom primitive.api.api.search.semantic_search import sync as semantic_search\nfrom primitive.api.models.semantic_search_input import SemanticSearchInput\n\nresults = semantic_search(\n    client=client,\n    body=SemanticSearchInput(query=\"invoice from Acme\", mode=\"hybrid\", limit=10),\n)\n```\n\nSemantic search requires the Pro plan and the `semantic_search_enabled` entitlement; callers without them receive a 403 error.\n\n## Errors\n\nThe generated functions do not raise `PrimitiveAPIError`; that mapping lives in the high-level client. A `sync` call returns the parsed model for the status the spec declares, so an error status parses into the generated `ErrorResponse` model rather than throwing. Import the `sync_detailed` variant (`from primitive.api.api.account.get_account import sync_detailed`) when you need the status code, headers, and raw content to build your own error handling. For the error shapes the high-level SDK raises, see the [Python SDK Error Reference](python-errors-reference).\n\n<Warning>\n\nEvery file under `src/primitive/api/` is regenerated wholesale on the next `make python-generate`. Any local edit there is silently discarded; put customizations in your own module that imports from `primitive.api` instead.\n\n</Warning>\n\n## Next steps\n\n<CardGroup cols={2}>\n\n<Card title=\"Client and Request Options\" href=\"python-client-options\">\n\nConfigure timeouts, dual-host base URLs, and per-call overrides on the high-level PrimitiveClient.\n\n</Card>\n\n<Card title=\"Python SDK Error Reference\" href=\"python-errors-reference\">\n\nLook up every PrimitiveAPIError, webhook error code, and x402 error condition the SDK can raise.\n\n</Card>\n\n<Card title=\"Registering Payout Addresses and Spend Policy\" href=\"python-x402-payout-and-policy\">\n\nUse the dedicated X402Client instead of the generated API module for payment operations.\n\n</Card>\n\n<Card title=\"Monorepo Structure and Release Process\" href=\"monorepo-and-releases\">\n\nSee how the shared OpenAPI spec propagates into the generated primitive.api module.\n\n</Card>\n\n</CardGroup>","canonical_base_url":"https://test.abhinandan.one","seo_indexing_enabled":true,"last_modified":"2026-08-21T18:22:43.359885+00:00","video_url":null,"voiceover_url":null,"tools_used":[],"demonstrated_by":[],"steps":[],"related_links":[],"intro":null,"prerequisites":[],"verification":[],"troubleshooting":[],"suggest_edit_url":"https://github.com/abhi-browzer/primitive-sdks/edit/main/sdk-python/src/primitive/client.py","raise_issue_url":"https://github.com/abhi-browzer/primitive-sdks/issues/new?title=Docs+feedback%3A+Generated+API+Client+%28Python%29&body=Page%3A+https%3A%2F%2Ftest.abhinandan.one%2Fpython-generated-api-client","page_feedback_enabled":true,"verified_ref":null,"verified_at":"2026-08-11T18:38:45.205849+00:00"}}