> ## Documentation Index > Fetch the complete documentation index at: https://docs.niadra.com/llms.txt > Use this file to discover all available pages before exploring further. # Gravar uma nota > Um procedimento, uma nota de ferramenta ou de processo, ou uma armadilha. Dado pessoal é recusado com 422. ## OpenAPI ````yaml openapi/pt/cell.json POST /v1/agent-memory/notes openapi: 3.1.0 info: title: API de dados da Niadra version: '1' description: >- Escrita, contexto, histórico, objetos, identidade, privacidade e governança de um espaço. Cada espaço tem um endereço estável, com o espaço e a região no nome. servers: - url: https://{space}.{region}.api.niadra.com variables: space: default: acme-prod description: O espaço, que vem na chave de fonte. region: default: us-east-2 description: A região do espaço, que também vem na chave. security: [] paths: /v1/agent-memory/notes: post: tags: - agent-memory summary: Gravar uma nota description: >- Grava uma nota de trabalho. 422 `personal_data_in_agent_memory` quando o título, o corpo ou as tags trazem dado pessoal: a nota é recusada, nunca mascarada. Uma fonte escreve até 20 notas por hora e guarda até o teto do espaço (500 por padrão). **Autenticação.** Chave de fonte com o escopo `agent_memory:write`, ou token de pessoa do Console com o papel `integration` (ou admin). operationId: create_note_v1_agent_memory_notes_post requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateAgentNoteRequest' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/RememberResult' description: A nota, ou o `proposal_id` da proposta que espera uma pessoa. '422': content: application/problem+json: schema: $ref: '#/components/schemas/Problem' description: O pedido não bate com o contrato. security: - sourceKey: [] - personToken: [] x-codeSamples: - lang: python label: Python source: >- # Needs the agent_memory:write scope; a note with personal data comes back refused saved = niadra.remember( "pitfall", "Scheduling API", "Dates without a time zone are refused; send the offset the customer's region uses.", tags=["scheduling"], ) if saved.error == "personal_data_in_agent_memory": ... # rewrite the note without the customer's data - lang: typescript label: TypeScript source: >- // Needs the agent_memory:write scope; a note with personal data comes back refused const { data, error } = await niadra.remember({ kind: "pitfall", title: "Scheduling API", body: "Dates without a time zone are refused; send the offset the customer's region uses.", tags: ["scheduling"], }); if (error?.code === "personal_data_in_agent_memory") { // rewrite the note without the customer's data } components: schemas: CreateAgentNoteRequest: additionalProperties: false properties: body: maxLength: 2000 minLength: 1 title: Body type: string evidence: anyOf: - $ref: '#/components/schemas/Evidence' - type: 'null' kind: $ref: '#/components/schemas/AgentNoteKind' source_id: anyOf: - format: uuid type: string - type: 'null' description: >- O agente dono. Uma chave de fonte escreve as próprias notas e pode omitir; uma pessoa nomeia o agente. title: Source Id tags: items: pattern: ^[a-z0-9][a-z0-9_.:-]{0,63}$ type: string maxItems: 8 title: Tags type: array title: maxLength: 120 minLength: 1 title: Title type: string valid_until: anyOf: - format: date-time type: string - type: 'null' title: Valid Until visibility: $ref: '#/components/schemas/AgentNoteVisibility' default: source required: - kind - title - body title: CreateAgentNoteRequest type: object RememberResult: additionalProperties: false description: >- O que `POST /v1/agent-memory/notes` responde: a nota, ou onde ela espera quando as escritas precisam de uma pessoa. properties: note: anyOf: - $ref: '#/components/schemas/AgentNote' - type: 'null' proposal_id: anyOf: - format: uuid type: string - type: 'null' description: >- Preenchido quando o espaço só aceita notas de agente por uma pessoa (`writes: human_only`). title: Proposal Id title: RememberResult type: object Problem: additionalProperties: false description: >- Detalhes do problema no formato da RFC 9457; `code` vem do catálogo de erros versionado. properties: code: title: Code type: string detail: anyOf: - type: string - type: 'null' default: null title: Detail request_id: anyOf: - type: string - type: 'null' default: null title: Request Id status: title: Status type: integer title: title: Title type: string type: default: about:blank title: Type type: string required: - title - status - code title: Problem type: object Evidence: additionalProperties: false description: 'De onde a nota veio: só o id, nunca o texto da conversa ou da tarefa.' properties: conversation_id: anyOf: - maxLength: 512 minLength: 1 type: string - type: 'null' title: Conversation Id task_id: anyOf: - maxLength: 512 minLength: 1 type: string - type: 'null' title: Task Id title: Evidence type: object AgentNoteKind: enum: - procedure - tool_note - process_note - pitfall title: AgentNoteKind type: string AgentNoteVisibility: enum: - source - vendor - space title: AgentNoteVisibility type: string AgentNote: additionalProperties: false properties: body: title: Body type: string created_at: format: date-time title: Created At type: string created_by: description: '`source:` ou `user:`.' title: Created By type: string evidence: anyOf: - $ref: '#/components/schemas/Evidence' - type: 'null' kind: $ref: '#/components/schemas/AgentNoteKind' note_id: format: uuid title: Note Id type: string origin: $ref: '#/components/schemas/AgentNoteOrigin' source_id: description: O agente dono da nota. format: uuid title: Source Id type: string status: $ref: '#/components/schemas/AgentNoteStatus' supersedes_note_id: anyOf: - format: uuid type: string - type: 'null' description: A versão que esta substituiu; aquela fica `retired`. title: Supersedes Note Id tags: items: type: string title: Tags type: array title: title: Title type: string valid_until: anyOf: - format: date-time type: string - type: 'null' description: Depois deste momento a nota sai do bloco e da busca. title: Valid Until version: minimum: 1 title: Version type: integer visibility: $ref: '#/components/schemas/AgentNoteVisibility' required: - note_id - source_id - visibility - kind - title - body - origin - version - status - created_at - created_by title: AgentNote type: object AgentNoteOrigin: enum: - agent - human - distilled title: AgentNoteOrigin type: string AgentNoteStatus: enum: - active - retired title: AgentNoteStatus type: string securitySchemes: sourceKey: type: http scheme: bearer description: nia_sk_... personToken: type: http scheme: bearer bearerFormat: JWT ````