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

# Mint a presigned S3 PUT URL

> Returns a single-use presigned PUT URL the customer uploads
bytes to directly. The returned `id` is an opaque handle
(`upl_...`) the customer then references via `POST /v1/sources`
(`type: "file"`) or `POST /v1/knowledge` (`type: "file"`) to
kick off ingestion.

The URL is bound to the supplied `contentType` and the
`Content-Length` cap — the customer cannot reuse the URL for
a different content type or larger payload.

Required scope: any valid key. Caps differ per content type
(audio/video up to 500 MB, image up to 25 MB, application/pdf
up to 100 MB, text/plain up to 25 MB).

Bytes are GC'd by an S3 lifecycle rule after 24 hours if
never referenced.




## OpenAPI

````yaml /openapi/v1.yaml post /uploads
openapi: 3.1.0
info:
  title: Scripe Public API
  version: '2026-08-01'
  summary: Read-only access to Scripe workspaces, projects, notes, posts, and sources.
  description: |
    The Scripe public API gives integrators stable, versioned read access
    to a workspace's content surface. Phase 2 ships read endpoints only;
    write endpoints land in Phase 3.

    All endpoints (except `/v1/health`) require a Bearer API key. Pin the
    API version with the `Scripe-Api-Version` request header to opt out
    of breaking changes.
  contact:
    name: Scripe Support
    url: https://scripe.io/support
    email: support@scripe.io
  license:
    name: Proprietary
servers:
  - url: https://api.scripe.io/v1
    description: Production
security:
  - BearerApiKey: []
tags:
  - name: Health
    description: Liveness and authenticated key smoke tests.
  - name: Workspace
    description: The workspace + principal resolved from your API key.
  - name: Projects
    description: Personal-brand, company-page, and amplifier projects.
  - name: Notes
    description: Project notes with paired calendar slot.
  - name: Posts
    description: Drafts, scheduled, and published LinkedIn posts.
  - name: Analytics
    description: Your own LinkedIn analytics and viral-post inspiration search.
  - name: Sources
    description: Transcriptions (audio/video sources) with truncated body.
  - name: Uploads
    description: >-
      Pre-signed S3 PUT URLs the customer uploads bytes to before referencing
      via Sources or Knowledge.
  - name: Knowledge
    description: >-
      Knowledge-base documents indexed for RAG. Async ingest via text, file,
      URL, or YouTube.
  - name: Jobs
    description: >-
      Async-job lifecycle — submitted via post-generation, knowledge ingest,
      file source.
  - name: Webhooks
    description: |
      Outbound HTTP callbacks. Subscribe an endpoint to one or more
      event names; we POST a signed JSON payload every time a matching
      event fires in the workspace. The signing secret is shown once
      on create and once on rotate — verify the
      `Webhook-Signature: t=<ts>,v1=<hmac>` header on every delivery.
paths:
  /uploads:
    post:
      tags:
        - Uploads
      summary: Mint a presigned S3 PUT URL
      description: |
        Returns a single-use presigned PUT URL the customer uploads
        bytes to directly. The returned `id` is an opaque handle
        (`upl_...`) the customer then references via `POST /v1/sources`
        (`type: "file"`) or `POST /v1/knowledge` (`type: "file"`) to
        kick off ingestion.

        The URL is bound to the supplied `contentType` and the
        `Content-Length` cap — the customer cannot reuse the URL for
        a different content type or larger payload.

        Required scope: any valid key. Caps differ per content type
        (audio/video up to 500 MB, image up to 25 MB, application/pdf
        up to 100 MB, text/plain up to 25 MB).

        Bytes are GC'd by an S3 lifecycle rule after 24 hours if
        never referenced.
      operationId: createUpload
      parameters:
        - $ref: '#/components/parameters/ScripeApiVersion'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UploadCreate'
      responses:
        '200':
          description: Presigned URL minted (or replayed via Idempotency-Key).
          headers:
            Idempotent-Replayed:
              schema:
                type: string
                enum:
                  - 'true'
                  - 'false'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadSingle'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/IdempotencyConflict'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          description: Upload subsystem unavailable (AWS creds missing).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  parameters:
    ScripeApiVersion:
      name: Scripe-Api-Version
      in: header
      required: false
      description: |
        Pin the API version. Format `YYYY-MM-DD`. Omit to receive the
        currently rolling default. Unknown versions return `400
        version_unsupported`.
      schema:
        type: string
        example: '2026-08-01'
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: |
        Opaque string (1–64 chars, `[A-Za-z0-9_-]`) used to dedup
        retried writes. Within 24h of the first request, the same key
        + same body returns the original response (`Idempotent-Replayed:
        true`). Same key + different body returns `409
        idempotency_key_conflict`.

        Strongly recommended for every write — see
        `/docs/api/v1/idempotency`.
      schema:
        type: string
        pattern: ^[A-Za-z0-9_-]{1,64}$
  schemas:
    UploadCreate:
      type: object
      required:
        - contentType
      properties:
        contentType:
          type: string
          example: audio/mpeg
          description: |
            MIME type of the file. Accepted families: `audio/*`,
            `video/*`, `image/*`, `application/pdf`,
            `application/msword` (+ Office Open XML variants),
            `text/plain`. Other types return `422 unprocessable`.
        maxSizeBytes:
          type: integer
          minimum: 1
          description: |
            Optional. Max bytes the customer expects to upload.
            Defaults to the per-content-type cap (500 MB for
            audio/video, 100 MB for PDF, etc.). Customer-supplied
            values over the cap return `422 unprocessable`.
    UploadSingle:
      type: object
      required:
        - data
      properties:
        data:
          $ref: '#/components/schemas/Upload'
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - request_id
            - docs_url
          properties:
            code:
              type: string
              description: Stable, machine-readable error identifier.
              example: not_found
            message:
              type: string
            request_id:
              type: string
              example: req_a1b2c3d4e5f6
            docs_url:
              type: string
              format: uri
            details:
              description: Optional structured payload — shape varies per code.
    Upload:
      type: object
      required:
        - id
        - uploadUrl
        - method
        - contentType
        - maxSizeBytes
        - expiresAt
      properties:
        id:
          type: string
          example: upl_acme_workspace_random_id_xxx
          description: |
            Opaque handle. Pass to `POST /v1/sources` (`type: "file"`)
            or `POST /v1/knowledge` (`type: "file"`) once bytes are
            uploaded.
        uploadUrl:
          type: string
          format: uri
          description: |
            Presigned S3 URL. Single-use; bound to the request's
            `contentType` and `Content-Length` cap.
        method:
          type: string
          enum:
            - PUT
        contentType:
          type: string
          example: audio/mpeg
        maxSizeBytes:
          type: integer
          minimum: 1
        expiresAt:
          type: string
          format: date-time
          description: When `uploadUrl` stops accepting new bytes (15 min from mint).
  responses:
    BadRequest:
      description: Malformed request (bad cursor, bad limit, etc.).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing, malformed, expired, or revoked API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Plan not eligible, scope missing, or workspace mismatch.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    IdempotencyConflict:
      description: |
        `Idempotency-Key` reused with a different body within the
        24h dedup window. Pick a fresh key or replay the original
        body verbatim.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unprocessable:
      description: Body shape was JSON but failed validation (`unprocessable`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Sliding-window rate limit exceeded.
      headers:
        Retry-After:
          schema:
            type: integer
        X-RateLimit-Limit:
          schema:
            type: integer
        X-RateLimit-Remaining:
          schema:
            type: integer
        X-RateLimit-Reset:
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    BearerApiKey:
      type: http
      scheme: bearer
      bearerFormat: scripe_sk_live_*
      description: |
        Pass `Authorization: Bearer scripe_sk_live_<...>` (or
        `scripe_sk_test_<...>` for test keys) on every request. Keys
        are scoped to a single workspace and can be revoked from the
        Scripe dashboard.

````