---
title: "Revise artifacts"
method: POST
path: "/api/v1/alpha/artifacts/revise"
tags: ["alpha"]
---

# Revise artifacts

`POST /api/v1/alpha/artifacts/revise`

## Request

- Base URL: `https://point11.ai`
- URL: `https://point11.ai/api/v1/alpha/artifacts/revise`
- Auth: OAuth 2 (authorization code, authorization URL `https://auth.point11.ai/oauth2/authorize`, token URL `https://auth.point11.ai/oauth2/token`)

Save an edited Markdown document as a new version of a document Alpha made; the version it was edited from stays unchanged. Returns the new version.

## Headers

- `Point11-Organization` string, uuid
- `Idempotency-Key` string, uuid, required

## Request body

- AlphaArtifactsReviseRequest
  - `revisesArtifactId` string, uuid: The latest version read by read_artifact when editing an existing document; omit only for a new document.
  - `brandKitArtifactId` string, uuid
  - `unbranded` boolean
  - `kind` 'markdown' | 'csv', required: markdown: a Markdown document. csv: a CSV file to download. Presentations use create_file with format pptx.
  - `title` string, required
  - `deliverable` boolean: false for a working file that only another step reads, such as a CSV written for run_analysis or create_file: it folds under the answer and stays out of the person's Files list. Omit it for a document or CSV the person asked for. A new version keeps its file's choice, so omit it with revisesArtifactId.
  - `markdown` string: The document. Required when kind is markdown.
  - `csv` string: The file's text: a header row first, RFC 4180 quoting, one record per line. Required when kind is csv.
  - `id` string, required: The ID of any version of a file Alpha made

## Response `200`

Success.

- AlphaArtifactsReviseResponse
  - `adSuite` AlphaAdSuite
    - `suiteId` string, uuid, required
    - `revisionId` string, uuid, required
    - `revision` integer, required
    - `href` string, required
    - `variantFailures` object[]
      - `variantId` string, required
      - `message` string, required
    - `findings` AlphaFindingsItem[]: Measured evidence from this render; absent when there is none.
      - union
        - object
          - `kind` 'text_overflow', required
          - `variantId` string, required
          - `layerIndex` integer, required
          - `layerId` string
          - `fontSize` integer, required
          - `width` object
            - `available` integer, required
            - `needed` integer, required
            - `lines` integer[], required
          - `height` object
            - `available` integer, required
            - `needed` integer, required
            - `linesShown` integer, required
            - `lines` integer, required
        - object
          - `kind` 'text_shrunk', required
          - `variantId` string, required
          - `layerIndex` integer, required
          - `layerId` string
          - `requestedFontSize` integer, required
          - `appliedFontSize` integer, required
          - `minFontSize` integer, required
        - object
          - `kind` 'text_fit_stopped', required
          - `variantId` string, required
          - `layerIndex` integer, required
          - `layerId` string
          - `reason` 'probe_limit' | 'call_budget', required: probe_limit: this layer's sizing search used its tries; call_budget: this call's shrink renders ran out.
          - `appliedFontSize` integer, required
        - object
          - `kind` 'safe_area', required
          - `variantId` string, required
          - `layerIndex` integer, required
          - `layerId` string
          - `overlap` object, required
            - `top` integer, required
            - `right` integer, required
            - `bottom` integer, required
            - `left` integer, required
        - object
          - `kind` 'contrast', required
          - `variantId` string, required
          - `layerIndex` integer, required
          - `layerId` string
          - `ratio` number, required
          - `required` union, required
            - 4.5
            - 3
          - `fontSize` integer, required
          - `textColor` string, required
          - `backgroundColor` string, required
        - object
          - `kind` 'recommended_length', required
          - `variantId` string, required
          - `presetId` string, required
          - `field` 'headline' | 'body', required
          - `length` integer, required
          - `recommended` integer, required
        - object
          - `kind` 'recommended_size', required
          - `variantId` string, required
          - `presetId` string, required
          - `width` integer, required
          - `height` integer, required
          - `recommended` object, required
            - `width` integer, required
            - `height` integer, required
        - object
          - `kind` 'image_asset', required
          - `variantId` string, required
          - `artifactId` string, uuid, required
          - `field` 'image' | 'logo', required
          - `aspectRatio` string, required
          - `width` integer
          - `height` integer
          - `byteLength` integer, required
          - `issues` string[], required
    - `findingsOmitted` integer: How many further findings this render measured past the ones listed.
    - `assets` object[], required
      - `artifactId` string, uuid, required
      - `variantId` string, required
      - `href` string, required
  - `artifactPackage` AlphaArtifactPackage
    - `version` 1, required
    - `creativeRound` object
      - `projectId` string, uuid, required
      - `roundId` string, uuid, required
      - `variantArtifactIds` string[], required
    - `creativeDeliverables` AlphaDeliverablesItem[]
      - `assetId` string, required
      - `format` string, required
      - `platforms` string[], required
      - `artifactIds` string[], required
      - `fileRoles` string[]
      - `primaryText` string
      - `headline` string
      - `longHeadline` string
      - `description` string
      - `businessName` string
      - `callToAction` string
      - `displayUrl` string
      - `destinationUrl` string
      - `path1` string
      - `path2` string
      - `headlines` string[]
      - `descriptions` string[]
      - `sitelinkTexts` string[]
      - `sitelinkDescriptions` string[]
      - `cardHeadlines` string[]
      - `cardDescriptions` string[]
      - `hashtags` string[]
      - `subjects` string[]
      - `preheader` string
      - `body` string
      - `messages` string[]
      - `script` string
      - `caption` string
      - `altText` string
    - `brief` string, required
    - `evidenceScope` string, required
    - `members` object[], required
      - `artifactId` string, uuid, required
      - `role` string, required
      - `dependsOn` string[], required
      - `changeNotes` string, required
  - `calculation` object
    - `status` 'recalculated' | 'unavailable', required
    - `engine` 'libreoffice', required
    - `formulaCount` integer, required
    - `findings` object[], required
      - `sheet` string, required
      - `cell` string, required
      - `error` string, required
  - `artifactId` string, uuid, required
  - `kind` 'markdown' | 'slides' | 'image' | 'audio' | 'video' | 'brand_kit' | 'presentation' | 'spreadsheet' | 'word' | 'pdf' | 'csv' | 'page', required
  - `title` string, required
  - `mediaType` 'text/markdown' | 'application/vnd.point11.slides+json' | 'image/png' | 'image/jpeg' | 'image/webp' | 'audio/mpeg' | 'audio/wav' | 'video/mp4' | 'video/webm' | 'application/vnd.point11.brand-kit+json' | 'application/vnd.openxmlformats-officedocument.presentationml.presentation' | 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' | 'application/vnd.openxmlformats-officedocument.wordprocessingml.document' | 'application/pdf' | 'text/csv' | 'text/html' | 'application/vnd.point11.website+json', required
  - `byteLength` integer, required
  - `status` 'ready'
  - `revisesArtifactId` string, uuid
  - `brandName` string
  - `slideCount` integer
  - `previewArtifactId` string, uuid
  - `previewFailure` 'render_failed' | 'invalid_preview' | 'upload_failed'
  - `websitePreview` AlphaWebsitePreview
    - `desktopArtifactId` string, uuid
    - `mobileArtifactId` string, uuid
    - `thumbnailArtifactId` string, uuid
    - `errorCount` integer, required
    - `consoleErrorCount` integer, required
    - `a11yViolationCount` integer, required
    - `a11yCriticalCount` integer, required
    - `states` object[]
      - `stateId` string, required
      - `path` string, required
      - `purpose` string, required
      - `device` 'desktop' | 'mobile', required
      - `finalPath` string, nullable, required
      - `screenshotArtifactId` string, uuid
      - `actions` object[], required
        - `index` integer, required
        - `kind` string, required
        - `status` 'completed' | 'failed' | 'skipped', required
      - `checks` object[], required
        - `id` string, required
        - `status` 'passed' | 'failed' | 'unavailable', required
        - `actual` union, required
          - string
          - boolean
      - `errorCount` integer, required
      - `consoleErrorCount` integer, required
      - `a11yViolationCount` integer, required
      - `failures` string[], required
    - `findings` object
      - `errors` object[], required
        - `message` string, required
        - `seenOn` string[], required
      - `consoleErrors` object[], required
        - `text` string, required
        - `seenOn` string[], required
      - `a11yViolations` object[], required
        - `id` string, required
        - `impact` 'minor' | 'moderate' | 'serious' | 'critical', nullable, required
        - `help` string, required
        - `targets` string[], required
        - `seenOn` string[], required
      - `brokenLinks` object[], required
        - `file` string, required
        - `reference` string, required
      - `brokenLinkCount` integer, required
      - `performance` object[]
        - `seenOn` string, required
        - `lcpMs` number, nullable, required
        - `cls` number, nullable, required
        - `fcpMs` number, nullable, required
        - `ttfbMs` number, nullable, required
        - `tbtMs` number, nullable, required
        - `transferBytes` integer, nullable, required
        - `imageBytes` integer, nullable, required
        - `requestCount` integer, nullable, required
      - `seo` object[]
        - `id` 'missing_title' | 'missing_description' | 'missing_lang' | 'missing_viewport' | 'image_missing_alt', required
        - `detail` string, required
        - `seenOn` string[], required
  - `websitePreviewFailure` 'capture_failed' | 'upload_failed'
  - `evidence` object[]
    - `kind` 'query_run' | 'verified_metric' | 'web_source' | 'attachment' | 'artifact', required
    - `id` string, required
    - `observedAt` string, date-time, required
  - `purpose` 'deliverable' | 'working'

## Other responses

- `400`: The input, query, or Idempotency-Key is invalid.
- `401`: The bearer is missing, expired, or not accepted.
- `402`: Billing refused the write: the code names the reason and `details.reason` carries it.
- `403`: The credential lacks the operation's scope or role, or the operation needs a different door.
- `404`: The resource or organization does not exist for this caller.
- `405`: This path takes another HTTP method, named in `Allow`.
- `409`: The request conflicts with current state or with prior use of its Idempotency-Key.
- `413`: The request, or the answer it asks for, is too large; narrow it.
- `429`: The credential's rate budget is spent; retry after `Retry-After` seconds.
- `500`: An unexpected server failure; retry later. Only `request_id` identifies it.
- `503`: A dependency is temporarily unavailable; retry after `Retry-After` seconds.
- `default`: Another status a product answers for its own refusal (for example `415` for an unsupported attachment); branch on `code`.

---

[API](https://skmtc.dev/point11/apis/point11-api.md) · [All operations](https://skmtc.dev/point11/apis/point11-api/llms.txt) · [OpenAPI document](https://skmtc.dev/point11/apis/point11-api/revisions/5241805fe425?raw)