> ## 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.

# Enviar estado

> Estado de um sistema de registro, até 1.000 itens: cada campo avança só quando a versão do item é maior que a que o escreveu por último. Escopo `state:push`.



## OpenAPI

````yaml openapi/pt/cell.json POST /v1/objects/push
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/objects/push:
    post:
      tags:
        - state
      summary: Enviar estado
      description: >-
        Estado de um sistema de registro: os itens de um objeto compartilhado
        são decididos contra a cópia quente do conjunto de trabalho, sem comando
        no banco, e gravados em até um segundo; os de um cliente, guardados num
        comando só.


        **Autenticação.** Chave de fonte: `Authorization: Bearer nia_sk_...`.
        Escopo exigido: `state:push`. Só responde num espaço com a
        funcionalidade `state` ligada (o documento `features`); num espaço sem
        ela, 404.
      operationId: push_objects_v1_objects_push_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ObjectPushRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectPushResponse'
          description: Resposta de sucesso.
        '422':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
          description: O pedido não bate com o contrato.
      security:
        - sourceKey: []
      x-codeSamples:
        - lang: python
          label: Python
          source: >-
            from niadra.models.state import ObjectPush, ObjectPushRequest,
            Provenance, StateRef


            # The system of record pushes what it knows; a field moves only
            under a greater version

            niadra.api.push_objects(ObjectPushRequest(objects=[
                ObjectPush(
                    ref=StateRef(type="item_variant", namespace="store", id="991"),
                    version=1042,
                    fields={"available": True, "price_sale": 199.9},
                    provenance=Provenance(source="live", source_observed_at=now),
                ),
            ]))
        - lang: typescript
          label: TypeScript
          source: >-
            // The system of record pushes what it knows; a field moves only
            under a greater version

            await niadra.api.pushObjects({
              objects: [
                {
                  ref: { type: "item_variant", namespace: "store", id: "991" },
                  version: 1042,
                  fields: { available: true, price_sale: 199.9 },
                  provenance: { source: "live", source_observed_at: now },
                },
              ],
            });
components:
  schemas:
    ObjectPushRequest:
      additionalProperties: false
      properties:
        objects:
          items:
            $ref: '#/components/schemas/ObjectPush'
          maxItems: 1000
          minItems: 1
          title: Objects
          type: array
      required:
        - objects
      title: ObjectPushRequest
      type: object
    ObjectPushResponse:
      additionalProperties: false
      description: >-
        Quantos itens do pedido tomaram cada decisão, contra a camada quente,
        sem nenhum comando no banco. O item de um objeto compartilhado é
        `applied` quando ao menos um campo dele avançou: as leituras o servem na
        hora, e o consolidador o grava em até um segundo com a mesma regra por
        campo, então o objeto gravado nunca discorda da resposta.
        `stale_version`: todo campo já tinha sido escrito por esta versão ou por
        uma maior, como um pedido repetido encontra. `out_of_set`: o objeto não
        está no conjunto de trabalho, e nada é guardado. O objeto de um cliente
        é `recorded`: aceito como evento de sistema sobre ele, no único comando
        do pedido, e os campos dele se movem pela mesma regra quando o evento é
        aplicado.
      properties:
        applied:
          title: Applied
          type: integer
        out_of_set:
          title: Out Of Set
          type: integer
        recorded:
          default: 0
          title: Recorded
          type: integer
        stale_version:
          title: Stale Version
          type: integer
      required:
        - applied
        - stale_version
        - out_of_set
      title: ObjectPushResponse
      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
    ObjectPush:
      additionalProperties: false
      properties:
        fields:
          additionalProperties: true
          maxProperties: 200
          minProperties: 1
          title: Fields
          type: object
        inputs:
          anyOf:
            - additionalProperties:
                maxLength: 256
                minLength: 1
                type: string
              maxProperties: 20
              propertyNames:
                maxLength: 256
                minLength: 1
              type: object
            - type: 'null'
          description: >-
            Para um objeto derivado de um cliente (uma cotação): os objetos de
            que os insumos dele são campos, pelo nome que o tipo lhes dá, como
            `type:namespace:id` (`{"lead": "lead:crm:L-9"}`). Quando um campo de
            um deles muda, o objeto vence, nomeando o insumo.
          title: Inputs
        provenance:
          $ref: '#/components/schemas/Provenance'
        ref:
          $ref: '#/components/schemas/StateRef'
        request_id:
          anyOf:
            - maxLength: 512
              minLength: 1
              type: string
            - type: 'null'
          description: >-
            O pedido de releitura que este item responde, do empréstimo do
            worker de resolução: o pedido é encerrado, e uma
            `watch_revalidation` é decidida sobre estes valores mesmo quando não
            são mais novos que os guardados.
          title: Request Id
        version:
          description: >-
            A versão do objeto na fonte. Um campo só se move quando ela é maior
            que a versão que o escreveu por último; uma fonte nunca reusa uma
            versão para outro conteúdo.
          maximum: 9007199254740991
          minimum: 0
          title: Version
          type: integer
      required:
        - ref
        - version
        - fields
        - provenance
      title: ObjectPush
      type: object
    Provenance:
      additionalProperties: false
      description: >-
        De onde vêm os valores enviados: só uma fonte `live` sustenta uma
        afirmação, e a idade de cada valor conta a partir de
        `source_observed_at`.
      properties:
        scope:
          default: global
          enum:
            - global
            - customer
            - context
          title: Scope
          type: string
        source:
          enum:
            - live
            - snapshot
            - cache
          title: Source
          type: string
        source_observed_at:
          format: date-time
          title: Source Observed At
          type: string
      required:
        - source
        - source_observed_at
      title: Provenance
      type: object
    StateRef:
      additionalProperties: false
      description: >-
        Um objeto do registro de tipos: de um cliente ou compartilhado, cuja
        chave pode nomear uma variante.
      properties:
        id:
          maxLength: 512
          minLength: 1
          title: Id
          type: string
        namespace:
          maxLength: 256
          minLength: 1
          title: Namespace
          type: string
        type:
          maxLength: 256
          minLength: 1
          title: Type
          type: string
        variant:
          anyOf:
            - maxLength: 256
              minLength: 1
              type: string
            - type: 'null'
          title: Variant
      required:
        - type
        - namespace
        - id
      title: StateRef
      type: object
  securitySchemes:
    sourceKey:
      type: http
      scheme: bearer
      description: nia_sk_...

````