> ## Documentation Index > Fetch the complete documentation index at: https://docs.myme.so/llms.txt > Use this file to discover all available pages before exploring further. # Create an item > Creates an item against its type schema and persists it. The server stamps `id`, `created_at`, `version`, and `source` (from the caller's credential — not forgeable). Type-schema validation runs before any write. If `source_id` is supplied and an existing non-trashed item in the tenant already has the same `(source, source_id)` pair, the call short-circuits to update — properties shallow-merge, tags replace if provided, edges replace per-type if provided. The HTTP status flips from 201 to 200; the response body is the updated item either way. See [Items — natural-key upsert](/concepts/items#natural-key-upsert) for the wider semantics. An `edges` block on the request body creates the item and its outbound edges in one transaction; either the whole write succeeds or nothing persists. See [Edges — atomic item + edges write](/concepts/edges#atomic-item--edges-write). ## OpenAPI ````yaml /openapi.json post /items openapi: 3.1.0 info: title: Marfa API version: 4.2.0 description: Typed data layer for structured personal data servers: [] security: [] paths: /items: post: tags: - Items summary: Create an item description: >- Creates an item against its type schema and persists it. The server stamps `id`, `created_at`, `version`, and `source` (from the caller's credential — not forgeable). Type-schema validation runs before any write. If `source_id` is supplied and an existing non-trashed item in the tenant already has the same `(source, source_id)` pair, the call short-circuits to update — properties shallow-merge, tags replace if provided, edges replace per-type if provided. The HTTP status flips from 201 to 200; the response body is the updated item either way. See [Items — natural-key upsert](/concepts/items#natural-key-upsert) for the wider semantics. An `edges` block on the request body creates the item and its outbound edges in one transaction; either the whole write succeeds or nothing persists. See [Edges — atomic item + edges write](/concepts/edges#atomic-item--edges-write). requestBody: content: application/json: schema: type: object properties: type: type: string properties: type: object additionalProperties: nullable: true id: type: string state: type: string timestamp: type: string source: type: string source_id: type: string tier: type: string enum: - library - feed device: type: string capture_latitude: type: number capture_longitude: type: number tags: type: array items: type: string edges: type: object additionalProperties: type: array items: type: string required: - type responses: '200': description: >- Item updated via natural-key upsert. Returned when both `source` (stamped from the credential) and request `source_id` resolve a non-trashed item in the caller's tenant — the request is treated as an idempotent re-sync of the upstream entry. content: application/json: schema: type: object properties: item: type: object properties: id: type: string type: type: string properties: type: object additionalProperties: nullable: true state: type: string enum: - active - archived - trashed - revoked tier: type: string enum: - library - feed tenant_id: type: string nullable: true version: type: number schema_version: type: integer source: type: string source_id: type: string device: type: string capture_latitude: type: number capture_longitude: type: number timestamp: type: string created_at: type: string updated_at: type: string edges: type: object additionalProperties: type: object properties: edges: type: array items: type: object properties: id: type: string tenant_id: type: string nullable: true source_id: type: string target_id: type: string edge_type: type: string properties: type: object additionalProperties: nullable: true created_at: type: string updated_at: type: string required: - id - source_id - target_id - edge_type - properties - created_at - updated_at has_more: type: boolean next_cursor: type: string required: - edges - has_more extensions: type: object additionalProperties: type: object additionalProperties: nullable: true required: - id - type - properties - state - version - schema_version - source - timestamp - created_at - updated_at metadata: type: object properties: item_id: type: string tags: type: array items: type: string extensions: type: object additionalProperties: nullable: true required: - item_id - tags - extensions required: - item - metadata '201': description: Item created content: application/json: schema: type: object properties: item: type: object properties: id: type: string type: type: string properties: type: object additionalProperties: nullable: true state: type: string enum: - active - archived - trashed - revoked tier: type: string enum: - library - feed tenant_id: type: string nullable: true version: type: number schema_version: type: integer source: type: string source_id: type: string device: type: string capture_latitude: type: number capture_longitude: type: number timestamp: type: string created_at: type: string updated_at: type: string edges: type: object additionalProperties: type: object properties: edges: type: array items: type: object properties: id: type: string tenant_id: type: string nullable: true source_id: type: string target_id: type: string edge_type: type: string properties: type: object additionalProperties: nullable: true created_at: type: string updated_at: type: string required: - id - source_id - target_id - edge_type - properties - created_at - updated_at has_more: type: boolean next_cursor: type: string required: - edges - has_more extensions: type: object additionalProperties: type: object additionalProperties: nullable: true required: - id - type - properties - state - version - schema_version - source - timestamp - created_at - updated_at metadata: type: object properties: item_id: type: string tags: type: array items: type: string extensions: type: object additionalProperties: nullable: true required: - item_id - tags - extensions required: - item - metadata '400': description: Validation error content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - validation_error - missing_required_field - invalid_type - invalid_id - invalid_properties - edge_constraint_violation - edge_cycle message: type: string details: type: object additionalProperties: nullable: true required: - code - message required: - error '401': description: Unauthorized content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - unauthorized message: type: string details: type: object additionalProperties: nullable: true required: - code - message required: - error '403': description: Forbidden content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - forbidden - type_not_permitted - edge_permission_denied message: type: string details: type: object additionalProperties: nullable: true required: - code - message required: - error security: - bearerAuth: [] components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API Key or OAuth Token description: Pass an API key (marfa_k1_...) or OAuth access token (marfa_at_...) ````