> ## Documentation Index > Fetch the complete documentation index at: https://docs.guidinghand.ai/llms.txt > Use this file to discover all available pages before exploring further. # Write a file > Creates the file, or replaces it, with this text. Text only: up to 1 MB a file, and 1,000 files and 25 MB an agent (past those, 413 and 409). Folders are part of the path and need no making; `.` and `..` aren’t allowed. The agent sees the change in its next tool call. Needs the admin role or an API key. ## OpenAPI ````yaml /api-reference/openapi.json put /v1/agents/{agent_id}/files/{path} openapi: 3.1.0 info: title: GuidingHand API version: 1.0.0 description: >- Create sessions (an invite link with a code for the person at the computer), run tasks on their computer with one of your agents, follow them, answer their questions and approvals, and fetch history and recordings. Test your agents with evals: test cases on fresh machines, run in test sets, scored by a check script or a rubric. Agents are versioned (save a draft, publish it), have tools (their own file system, and your HTTP endpoints), and every change is in the org’s audit log. servers: - url: https://guidinghand.ai description: Production - url: https://dev.guidinghand.ai description: Development (Stripe test mode) security: - bearerAuth: [] tags: - name: Agents - name: Agent files - name: Agent tools - name: Sessions - name: Tasks - name: Webhooks - name: Audit log - name: Test cases - name: Test sets - name: Test runs - name: Start states - name: Runners paths: /v1/agents/{agent_id}/files/{path}: parameters: - name: agent_id in: path required: true description: The agent’s id, e.g. `billing` or `default`. schema: type: string - name: path in: path required: true description: >- The file’s path, like `notes/customers.md` (with its slashes as they are, or encoded as `%2F`). schema: type: string put: tags: - Agent files summary: Write a file description: >- Creates the file, or replaces it, with this text. Text only: up to 1 MB a file, and 1,000 files and 25 MB an agent (past those, 413 and 409). Folders are part of the path and need no making; `.` and `..` aren’t allowed. The agent sees the change in its next tool call. Needs the admin role or an API key. operationId: putAgentFile requestBody: required: true content: application/json: schema: type: object required: - content properties: content: type: string description: The whole text of the file. example: |- # Returns Within 30 days, with the receipt. responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/AgentFile' '400': $ref: '#/components/responses/E400' '401': $ref: '#/components/responses/E401' '403': $ref: '#/components/responses/E403' '404': $ref: '#/components/responses/E404' '409': $ref: '#/components/responses/E409' '413': $ref: '#/components/responses/E413' components: schemas: AgentFile: type: object properties: object: const: agent_file agent_id: type: string example: billing path: type: string example: /notes/customers.md description: Always starts with `/`. bytes: type: integer description: Its size in UTF-8. created_at: type: string format: date-time updated_at: type: string format: date-time updated_by: $ref: '#/components/schemas/FileEditor' content: type: string description: The file’s text. Only when you get or write one file. FileEditor: oneOf: - title: Person type: object description: A person in the org (in the console). properties: type: const: user email: type: - string - 'null' example: jane@acme.com - title: API key type: object description: One of the org’s API keys. properties: type: const: api_key key_id: type: string name: type: - string - 'null' example: Zendesk prefix: type: - string - 'null' description: The key’s first characters. example: gh_live_AbC1 - title: Agent type: object description: 'An agent during a task: its own file writes.' properties: type: const: agent task_id: type: string - type: 'null' description: >- Who last wrote the file: a person, an API key, or the agent itself during a task (`task_id`). Error: type: object required: - error properties: error: type: object required: - type - message properties: type: type: string enum: - invalid_request - authentication - payment_required - permission - not_found - conflict - rate_limit - server_error message: type: string code: type: string description: >- Why it was refused, when there’s more to say than the status. Starting a task: `insufficient_balance`, `auto_topup_limit_reached` or `card_needs_attention` (402: the balance can’t cover a minute; add funds, raise the auto top-up limit, or update the card), `concurrency_limit` (429), `model_unavailable` (503: the agent’s `model` can’t run on this server; choose another). On `/respond`: `already_answered` (someone answered or decided first: see `answered_by`) or `not_pending` (that question or approval isn’t open any more). The GuidingHand app hears two more, which the API never returns: `customer_answers_off` and `customer_approvals_off` (the agent keeps its questions or approvals for your team). Deleting a start state that test cases use: `in_use` (409, with `test_case_ids`). answered_by: type: string enum: - customer - operator - timeout description: >- With `already_answered`: who answered or decided first (`customer`: the person at the computer; `timeout`: nobody decided an approval within the agent’s `approval_timeout_minutes`, so it was denied). test_case_ids: type: array items: type: string description: 'With `in_use`: the test cases that use the start state.' responses: E400: description: The request is invalid. content: application/json: schema: $ref: '#/components/schemas/Error' E401: description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/Error' E403: description: Your role can’t do this. content: application/json: schema: $ref: '#/components/schemas/Error' E404: description: Not found in this org. content: application/json: schema: $ref: '#/components/schemas/Error' E409: description: >- Conflicts with the current state (e.g. no computer connected, a task already running, nothing pending, no draft to publish, an agent’s file limits). content: application/json: schema: $ref: '#/components/schemas/Error' E413: description: 'Too large: a file over 1 MB.' content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer description: An org API key (`gh_live_…`) from Settings → API keys in the console. ````