> ## Documentation Index > Fetch the complete documentation index at: https://docs.ergoly.ai/llms.txt > Use this file to discover all available pages before exploring further. # Read a memory tier > Three answers, chosen by the query and never by the state of anything. No `repoId` lists the tiers this ework can reach — start here, it is how you learn the ids. `repoId` alone lists what is at `path`, the repository root by default. Adding `read` returns the file itself, with the `sha` a later write can pass as `expectedSha`, and flags saying whether it is binary or was truncated. ## OpenAPI ````yaml /openapi.json get /api/v1/eworks/{id}/memory openapi: 3.1.0 info: title: Ergoly platform API version: 1.0.0 description: >- Read and change one organization's own Ergoly environment. Every route is scoped to the organization the presented credential resolves to; there is no parameter that widens it. The human-readable reference is served from the same namespace at `/api/v1/docs`, behind the same credential. The namespace's front door is `GET /api/v1`, and it is deliberately absent from `paths` below. It answers without a credential — what this API is, how an organization admin mints a key, and where the reference lives — so it is the way in to this contract rather than a part of it: it has no scope, takes no parameters, and there is nothing about it for a generated client to call. Every `unauthorized` refusal carries that same URL as `error.docs`. servers: - url: https://control.ergoly.ai security: - orgApiKey: [] tags: - name: auth description: How to present a key, what it is scoped to, and what a 401 means. - name: organization description: Which organization your credential resolves to. - name: workers description: The Slack apps and bot identities in your organization. - name: eworks description: The runtime instances under a Worker — one core, one per bound Client. - name: clients description: The customers a Worker can be scoped to, and how to bind one. - name: channels description: Which Slack rooms a Worker answers in, and who it answers as. - name: tasks description: >- Tasks handed between Workers and people, scheduled jobs, their targets, and their run history. - name: jobs description: How a provisioning run is going — the other half of every 202. - name: memory description: Read and write the memory tiers an ework mounts. - name: connections description: The credentials your agents use, and the hosts they are injected on. - name: webhooks description: Inbound URLs an outside system can POST to, each of which starts a turn. - name: activity description: Your organization's audit feed. - name: usage description: Cost, turn outcomes and a per-day pulse over a window you choose. - name: errors description: The closed set of refusal codes, and what to do about each. paths: /api/v1/eworks/{id}/memory: get: tags: - memory summary: Read a memory tier description: >- Three answers, chosen by the query and never by the state of anything. No `repoId` lists the tiers this ework can reach — start here, it is how you learn the ids. `repoId` alone lists what is at `path`, the repository root by default. Adding `read` returns the file itself, with the `sha` a later write can pass as `expectedSha`, and flags saying whether it is binary or was truncated. operationId: readMemory parameters: - name: id in: path required: true description: >- The ework id. A malformed id answers 404, exactly as another organization's well-formed id does. schema: type: string description: >- The ework id. A malformed id answers 404, exactly as another organization's well-formed id does. - name: repoId in: query required: false description: >- Which tier to read. Omit it and the answer is `{tierRepos: […]}` — the tiers this ework can reach, which is how you discover the ids the other calls take. schema: type: string description: >- Which tier to read. Omit it and the answer is `{tierRepos: […]}` — the tiers this ework can reach, which is how you discover the ids the other calls take. - name: path in: query required: false description: Path from the repository root. Defaults to the root. schema: type: string description: Path from the repository root. Defaults to the root. - name: read in: query required: false description: >- Any non-empty value asks for the FILE at `path` (`{file: …}`) rather than a listing (`{entries: […]}`). schema: type: string description: >- Any non-empty value asks for the FILE at `path` (`{file: …}`) rather than a listing (`{entries: […]}`). responses: '200': description: Success. content: application/json: schema: type: object properties: data: oneOf: - type: object description: No `repoId` was given. properties: tierRepos: type: array items: $ref: '#/components/schemas/TierRepo' description: Every tier this ework can reach. required: - tierRepos additionalProperties: false - type: object description: A listing. properties: entries: type: array items: $ref: '#/components/schemas/TierEntry' description: What is at `path`. required: - entries additionalProperties: false - type: object description: One file, because `read` was set. properties: file: $ref: '#/components/schemas/TierFile' required: - file additionalProperties: false description: >- Which of the three shapes comes back is decided by the query, not by the state of anything. required: - data additionalProperties: false example: data: tierRepos: - id: 4a5b6c7d-8e9f-4012-8345-67890abcdef1 tier: client githubRepoName: client-northwind-acme workerId: 8f1c2d3e-9a4b-4c5d-8e6f-1a2b3c4d5e6f clientId: c1a2b3c4-d5e6-4f70-8912-3a4b5c6d7e8f eworkId: null clientSlug: acme clientName: Acme Corp workerName: Rowan orgName: null eworkTier: null '401': description: '`unauthorized`' content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: '`not_found`' content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: '`rate_limited`' content: application/json: schema: $ref: '#/components/schemas/Error' security: - orgApiKey: - eworks:read components: schemas: TierRepo: type: object description: One memory tier reachable from this ework. properties: id: type: string description: The repository id — what `repoId` takes on every memory call. tier: type: string enum: - instance - client - worker - org description: >- Which tier this repository is. The ladder is instance > client > worker > org. githubRepoName: type: string description: The backing repository name. workerId: type: - string - 'null' description: The Worker this tier belongs to, when it is Worker-scoped. clientId: type: - string - 'null' description: The Client this tier belongs to, when it is Client-scoped. eworkId: type: - string - 'null' description: The ework this tier belongs to, on the `instance` tier. clientSlug: type: - string - 'null' description: The Client slug, on a `client` row. clientName: type: - string - 'null' description: The Client's name, on a `client` row. workerName: type: - string - 'null' description: The Worker's display name, on a `worker` or `instance` row. orgName: type: - string - 'null' description: The organization's name, on an `org` row. eworkTier: type: - string - 'null' description: >- Which tier of ework an `instance` row belongs to: `core` or `client`. required: - id - tier - githubRepoName - workerId - clientId - eworkId - clientSlug - clientName - workerName - orgName - eworkTier additionalProperties: false TierEntry: type: object description: One entry in a memory tier listing. properties: type: type: string enum: - file - dir description: What the entry is. name: type: string description: The entry's own name. path: type: string description: Path from the repository root. size: type: integer description: Size in bytes. 0 for a directory. required: - type - name - path - size additionalProperties: false TierFile: type: object description: One memory-tier file. properties: path: type: string description: Path from the repository root. text: type: string description: The file's text. Empty when `binary` is true. size: type: integer description: Size in bytes. binary: type: boolean description: True when the file is not text. sha: type: string description: >- The blob sha. Pass it back as `expectedSha` to refuse a write that would clobber a change made since. truncated: type: boolean description: >- True when `text` holds only the head of a larger file. Do not write a truncated body back. required: - path - text - size - binary - sha - truncated additionalProperties: false Error: type: object description: The one error shape. Every refusal in this namespace has it. properties: error: type: object description: The refusal. properties: code: type: string enum: - unauthorized - not_found - invalid_request - conflict - quota_exceeded - rate_limited - upstream_error - gone description: The machine-stable half. Branch on this, never on `message`. message: type: string description: Prose for a human reading a terminal. docs: type: string description: >- Where to learn how to authenticate. Present on `unauthorized` and on nothing else — it is the one refusal a caller can reach with no credential at all, so it is the one that has to say where the way in is. required: - code - message additionalProperties: false required: - error additionalProperties: false securitySchemes: orgApiKey: type: http scheme: bearer description: >- An organization-scoped API key, minted in control under Settings → API keys. Every failure to authenticate answers one identical 401: "Provide a valid organization-scoped API key or an active session." Each operation names the one scope it is filed under, `:`, where the resource is the first path segment after `/api/v1/`; a key minted today carries all 22 of them. Scopes are RECORDED — on the key and on every audit row — and are not yet enforced: no request is refused for want of one. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.