> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jelou.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Obter um registro

> Obtenha um único registro de memória de um usuário por chave

## Descrição

Retorna um único registro de memória de um usuário pela sua `key`, identificado por `userReferenceId` e `botId`.

## Endpoint

```
POST https://gateway.jelou.ai/workflows/v2/memory/users/find-one
```

## Parâmetros do corpo

<ParamField body="userReferenceId" type="string" required>
  Identificador de referência externo do usuário.
</ParamField>

<ParamField body="botId" type="string" required>
  Identificador do bot associado à memória.
</ParamField>

<ParamField body="key" type="string" required>
  Chave do registro a obter.
</ParamField>

## Autenticação

Todas as requisições devem incluir o cabeçalho `x-api-key` com uma API key que tenha o scope `memory:read`.

```
x-api-key: API_KEY
```

## Exemplo de solicitação

```bash cURL theme={null}
curl --request POST \
  --url https://gateway.jelou.ai/workflows/v2/memory/users/find-one \
  --header 'x-api-key: API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "userReferenceId": "USER_REFERENCE_ID",
    "botId": "BOT_ID",
    "key": "paso"
  }'
```

## Respostas

| Código | Estado                | Descrição                                           |
| ------ | --------------------- | --------------------------------------------------- |
| 200    | OK                    | Registro obtido com sucesso.                        |
| 401    | Unauthorized          | Credenciais de autenticação inválidas ou ausentes.  |
| 403    | Forbidden             | A API key não tem o scope `memory:read`.            |
| 404    | Not Found             | Não existe um registro com a chave indicada.        |
| 422    | Unprocessable Entity  | Faltam campos obrigatórios ou o formato é inválido. |
| 500    | Internal Server Error | Erro interno do servidor.                           |

## Exemplo de resposta

```json theme={null}
{
  "status": "success",
  "message": "Record retrieved successfully",
  "data": "confirmacion"
}
```


## OpenAPI

````yaml POST /v2/memory/users/find-one
openapi: 3.1.0
info:
  title: Jelou API
  description: >-
    API for the Jelou platform. Send messages, manage campaigns, handle
    conversations, users, databases, and widgets.
  version: 1.0.0
servers:
  - url: https://api.jelou.ai
    description: Production server
security:
  - basicAuth: []
tags:
  - name: Messages
    description: Send messages to users
  - name: Campaigns
    description: HSM campaigns and templates
  - name: Conversations
    description: Chat history and metrics
  - name: Users
    description: User state and cache management
  - name: Resources
    description: Media resource management
  - name: Datum
    description: Database CRUD operations
  - name: Widget
    description: Widget and room management
  - name: PMA Custom
    description: External support panel integration
  - name: Memory
    description: Per-user session memory management (Memory API v2)
paths:
  /v2/memory/users/find-one:
    servers:
      - url: https://gateway.jelou.ai/workflows
        description: Memory API
    post:
      tags:
        - Memory
      summary: Get one record
      description: >-
        Returns a single memory record of a user by key, identified by
        userReferenceId and botId.
      operationId: findOneMemoryRecord
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - userReferenceId
                - botId
                - key
              properties:
                userReferenceId:
                  type: string
                  description: External reference identifier of the user.
                botId:
                  type: string
                  description: Identifier of the bot associated with the memory.
                key:
                  type: string
                  description: Key of the record to retrieve.
      responses:
        '200':
          description: Record retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  message:
                    type: string
                    example: Record retrieved successfully
                  data:
                    description: The stored value for the requested key. Any JSON type.
              example:
                status: success
                message: Record retrieved successfully
                data: confirmacion
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - apiKey: []
components:
  responses:
    Unauthorized:
      description: Unauthorized - Invalid authentication credentials
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: >-
        Forbidden - The API key lacks the required scope (memory:read /
        memory:write)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Not found - Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UnprocessableEntity:
      description: Unprocessable entity - Validation error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        message:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
        statusMessage:
          type: string
        status:
          type: integer
        error:
          type: object
          properties:
            code:
              type: string
            key:
              type: string
            description:
              type: string
            developerMessages:
              type: object
            clientMessages:
              type: object
        validationError:
          type: object
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Basic authentication using Base64 encoded clientId:clientSecret
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: API key del proyecto de Jelou

````