> ## Documentation Index > Fetch the complete documentation index at: https://docs.useorgx.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Register an artifact > Register a produced piece of work against the entity it belongs to. One of `artifact_url` or `external_url` is required. The target entity determines the workspace. Statuses that assert a human ruling (`approved`, `rejected`) are refused on this path; an automated reviewer records `eval_passed` instead. Reuse the same `Idempotency-Key` and request body to safely retry a timed-out create; reusing a key with a different body returns a conflict. ## OpenAPI ````yaml /openapi/v1.yaml post /artifacts openapi: 3.1.0 info: title: OrgX REST API v1 version: '1' description: >- Build accountable work into your product with OrgX REST API v1. Create work with one field, attach evidence when it is complete, and keep the receipt. Every authenticated request is scoped to the workspace resolved from your credential. Start with `POST /work`. Human guide: https://docs.useorgx.com/docs/api/quickstart contact: name: OrgX Support url: https://useorgx.com/support email: support@useorgx.com license: name: Proprietary url: https://useorgx.com/terms servers: - url: https://useorgx.com/api/v1 description: Production security: [] tags: - name: Work description: Create accountable work and complete it with evidence - name: Initiatives description: Organize related work around an outcome - name: Operating processes description: Evidence-backed company workflow/process lifecycle - name: Operating map description: Derived, rebuildable Operating Map projection over the process ledger - name: Discovery runs description: Wizard and deep-search workflow discovery over connected company sources - name: Handoffs description: Ledger-backed stage handoffs between operating-process stages - name: Events description: Replayable, workspace-scoped accepted ledger events - name: Projections description: Workspace-scoped, rebuildable read projections over OrgX sources - name: Episodes description: Mission-compatible Episode read adapters - name: Receipt validation description: Account-free Agent Work Receipt schema discovery and conformance - name: Receipt import description: Authenticated, workspace-scoped import into the hosted receipt ledger - name: Workload diagnosis description: >- Account-free evaluation of time, agents, systems, authority, and accountability boundaries - name: Content Studio description: >- Estimate, showcase, checkout, and payment event operations for Content Studio - name: Decisions description: Raise decisions for human ruling and read their state - name: Artifacts description: Register produced work against the entity it belongs to - name: Launches description: Preview and run an initiative launch through its spend gates - name: Runs description: Control agent runs with pause, resume, cancel, and rollback - name: Lifecycle description: Pause, resume, retry, or cancel work hierarchy nodes and runs - name: Deduplication description: Claim durable event fingerprints so duplicate triggers fire once - name: Credential description: >- Resolve the calling credential, the workspaces it reaches, and what it may do - name: API discovery description: Account-free error codes, request schemas, and closed vocabularies for v1 externalDocs: description: Human-readable OrgX REST API v1 reference url: https://docs.useorgx.com/docs/api/public-api paths: /artifacts: post: tags: - Artifacts summary: Register an artifact description: >- Register a produced piece of work against the entity it belongs to. One of `artifact_url` or `external_url` is required. The target entity determines the workspace. Statuses that assert a human ruling (`approved`, `rejected`) are refused on this path; an automated reviewer records `eval_passed` instead. Reuse the same `Idempotency-Key` and request body to safely retry a timed-out create; reusing a key with a different body returns a conflict. operationId: createArtifact parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ArtifactCreateRequest' example: entity_type: task entity_id: 7fbb727d-17c4-4bc7-9fc7-60eb15e9314d name: Launch plan review notes artifact_type: shared.project_handbook artifact_url: https://example.com/review.md responses: '200': description: >- The artifact returned for a safe replay with the same Idempotency-Key content: application/json: schema: $ref: '#/components/schemas/ArtifactCreateResponse' example: data: id: 3a2b1c0d-9e8f-4a7b-8c6d-5e4f3a2b1c0d workspace_id: 11111111-1111-4111-8111-111111111111 name: Launch plan review notes artifact_type: shared.project_handbook artifact_url: https://example.com/review.md entity_type: task entity_id: 7fbb727d-17c4-4bc7-9fc7-60eb15e9314d status: draft version: 1 meta: apiVersion: '1' artifactTypeFallback: false effectiveArtifactType: shared.project_handbook duplicate: true '201': description: Artifact registered content: application/json: schema: $ref: '#/components/schemas/ArtifactCreateResponse' example: data: id: 3a2b1c0d-9e8f-4a7b-8c6d-5e4f3a2b1c0d workspace_id: 11111111-1111-4111-8111-111111111111 name: Launch plan review notes artifact_type: shared.project_handbook artifact_url: https://example.com/review.md entity_type: task entity_id: 7fbb727d-17c4-4bc7-9fc7-60eb15e9314d status: draft version: 1 created_at: '2026-08-19T15:10:00.000Z' updated_at: '2026-08-19T15:10:00.000Z' meta: apiVersion: '1' artifactTypeFallback: false effectiveArtifactType: shared.project_handbook duplicate: false '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': description: The Idempotency-Key was already used with a different request body content: application/json: schema: $ref: '#/components/schemas/ApiError' '503': $ref: '#/components/responses/ServiceUnavailable' security: - bearerAuth: [] components: parameters: IdempotencyKey: name: Idempotency-Key in: header required: true schema: type: string minLength: 1 maxLength: 200 pattern: ^[A-Za-z0-9][A-Za-z0-9._:/-]{0,199}$ description: Workspace-scoped retry key for safe mutation replay. schemas: ArtifactCreateRequest: type: object additionalProperties: false required: - entity_type - entity_id - name - artifact_type description: One of `artifact_url` or `external_url` is required. properties: entity_type: type: string enum: - project - initiative - workstream - milestone - task - decision entity_id: type: string format: uuid name: type: string minLength: 1 maxLength: 500 artifact_type: type: string minLength: 1 maxLength: 120 artifact_url: type: string maxLength: 2000 external_url: type: string maxLength: 2000 description: type: - string - 'null' maxLength: 4000 preview_markdown: type: string maxLength: 25000 initiative_id: type: string format: uuid status: type: string enum: - draft - in_review - changes_requested - superseded - archived metadata: type: object additionalProperties: true created_by_type: type: string enum: - human - agent created_by_id: type: string format: uuid ArtifactCreateResponse: type: object required: - data - meta additionalProperties: false properties: data: $ref: '#/components/schemas/Artifact' meta: $ref: '#/components/schemas/ArtifactCreateMeta' ApiError: type: object properties: error: type: object properties: code: type: string message: type: string details: type: object requestId: type: string timestamp: type: string format: date-time docsUrl: type: string format: uri retryAfter: type: integer description: Seconds until rate limit resets Artifact: type: object description: A registered piece of produced work attached to a workspace entity. additionalProperties: false required: - id - workspace_id - name - artifact_type - entity_type - entity_id - status properties: id: type: string format: uuid workspace_id: type: string format: uuid name: type: string description: type: - string - 'null' artifact_type: type: string artifact_url: type: - string - 'null' entity_type: type: string entity_id: type: string format: uuid status: type: string enum: - draft - in_review - approved - changes_requested - rejected - eval_passed - superseded - archived version: type: integer metadata: type: object additionalProperties: true verification: type: object additionalProperties: true created_by_type: type: string created_by_id: type: string format: uuid agent_type: type: - string - 'null' eval_status: type: - string - 'null' latest_eval_run_id: type: - string - 'null' format: uuid eval_triggered_at: type: - string - 'null' format: date-time created_at: type: string format: date-time updated_at: type: string format: date-time ArtifactCreateMeta: type: object additionalProperties: false required: - apiVersion - artifactTypeFallback - effectiveArtifactType - duplicate properties: apiVersion: type: string artifactTypeFallback: type: boolean effectiveArtifactType: type: string duplicate: type: boolean description: True when this response is the stored result of a replay. responses: BadRequest: description: Request validation failed content: application/json: schema: $ref: '#/components/schemas/ApiError' Unauthorized: description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ApiError' Forbidden: description: The caller is authenticated but cannot command this workspace content: application/json: schema: $ref: '#/components/schemas/ApiError' NotFound: description: Resource is unavailable to the caller content: application/json: schema: $ref: '#/components/schemas/ApiError' ServiceUnavailable: description: Ledger or workspace authorization is unavailable content: application/json: schema: $ref: '#/components/schemas/ApiError' securitySchemes: bearerAuth: type: http scheme: bearer description: 'OrgX API key, sent as `Authorization: Bearer oxk_...`' ````