ShipRust Projects API

openapi: 3.2.0
info:
  title: ShipRust Projects API
  description: 'Create and download ShipRust projects with a personal API key. Create a key in Settings and send it as `Authorization: Bearer sr_...`. Every error is a JSON object with an `error` message. Guide: https://shiprust.com/docs/api'
  license:
    name: Proprietary
  version: '1'
tags:
- name: Projects
  description: Generated projects
paths:
  /api/v1/options:
    get:
      tags:
      - Projects
      summary: 'Hosting choices, capability keys, defaults and limits: the same options as the…'
      operationId: list_options
      responses:
        '200':
          description: The options
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Options'
  /api/v1/projects:
    get:
      tags:
      - Projects
      summary: Your projects, newest first. Listing needs no paid access
      operationId: list_projects
      responses:
        '200':
          description: Your projects
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectList'
        '401':
          description: Missing, invalid or revoked key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
      security:
      - api_key: []
    post:
      tags:
      - Projects
      summary: Create a project with the same choices and validation as the new-project form
      operationId: create_project
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRequest'
        required: true
      responses:
        '201':
          description: The new project
          headers:
            Location:
              schema:
                type: string
              description: The new project's URL
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '400':
          description: The body is not a JSON object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '401':
          description: Missing, invalid or revoked key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '402':
          description: The account has no lifetime access yet
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '409':
          description: The slug is already taken
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '422':
          description: Invalid choices or unknown fields
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
      security:
      - api_key: []
  /api/v1/projects/{id}:
    get:
      tags:
      - Projects
      summary: One of your projects
      operationId: get_project
      parameters:
      - name: id
        in: path
        description: The project's id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: The project
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '401':
          description: Missing, invalid or revoked key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '402':
          description: The account has no lifetime access yet
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '404':
          description: No such project on this account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
      security:
      - api_key: []
    delete:
      tags:
      - Projects
      summary: Remove a project from your list. Downloaded zips are unaffected
      operationId: delete_project
      parameters:
      - name: id
        in: path
        description: The project's id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Deleted
        '401':
          description: Missing, invalid or revoked key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '404':
          description: No such project on this account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
      security:
      - api_key: []
  /api/v1/projects/{id}/download:
    get:
      tags:
      - Projects
      summary: The generated zip, identical to the site's download
      operationId: download_project
      parameters:
      - name: id
        in: path
        description: The project's id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: The project zip
          headers:
            Content-Disposition:
              schema:
                type: string
              description: '`attachment; filename="<slug>.zip"`'
          content:
            application/zip:
              schema:
                $ref: '#/components/schemas/ProjectZip'
        '401':
          description: Missing, invalid or revoked key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '402':
          description: The account has no lifetime access yet
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '404':
          description: No such project on this account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
      security:
      - api_key: []
components:
  schemas:
    Capability:
      type: object
      description: A capability key for `sentry_features` or `posthog_features`.
      required:
      - key
      - label
      - description
      properties:
        description:
          type: string
        key:
          type: string
          example: sentry-errors
        label:
          type: string
    Options:
      type: object
      description: The generator's choices, their defaults and the input limits.
      required:
      - template_version
      - hosts
      - sentry_features
      - posthog_features
      - defaults
      - limits
      properties:
        defaults:
          $ref: '#/components/schemas/Defaults'
        hosts:
          type: array
          items:
            $ref: '#/components/schemas/Choice'
        limits:
          $ref: '#/components/schemas/Limits'
        posthog_features:
          type: array
          items:
            $ref: '#/components/schemas/Capability'
        sentry_features:
          type: array
          items:
            $ref: '#/components/schemas/Capability'
        template_version:
          type: string
          description: The template revision new projects are generated from.
    Project:
      type: object
      description: A generated project and the choices it was generated with.
      required:
      - id
      - name
      - slug
      - description
      - host
      - include_blog
      - include_docs
      - include_auth
      - include_google
      - include_github
      - include_stripe
      - include_api
      - include_mcp
      - include_storage
      - include_qdrant
      - sentry_features
      - posthog_features
      - template_version
      - created_at
      - url
      - download_url
      properties:
        created_at:
          type: string
          format: date-time
        description:
          type: string
        download_url:
          type: string
          description: The project's zip, `GET` with the same key.
        host:
          type: string
          example: caprover
        id:
          type: string
          format: uuid
        include_api:
          type: boolean
        include_auth:
          type: boolean
        include_blog:
          type: boolean
        include_docs:
          type: boolean
        include_github:
          type: boolean
        include_google:
          type: boolean
        include_mcp:
          type: boolean
        include_qdrant:
          type: boolean
        include_storage:
          type: boolean
        include_stripe:
          type: boolean
        name:
          type: string
        posthog_features:
          type: array
          items:
            type: string
        sentry_features:
          type: array
          items:
            type: string
        slug:
          type: string
        template_version:
          type: string
          description: The template revision the project's zip is generated from.
        url:
          type: string
          description: This project in the API.
    ProjectZip:
      type: string
      format: binary
      description: A project's generated zip archive.
    SlugLimit:
      type: object
      required:
      - max
      - pattern
      properties:
        max:
          type: integer
          minimum: 0
        pattern:
          type: string
    MaxLength:
      type: object
      required:
      - max
      properties:
        max:
          type: integer
          minimum: 0
    ErrorBody:
      type: object
      description: The body of every error response.
      required:
      - error
      properties:
        error:
          type: string
          description: What went wrong, written for a person.
          example: This API key is invalid or has been revoked.
    Range:
      type: object
      required:
      - min
      - max
      properties:
        max:
          type: integer
          minimum: 0
        min:
          type: integer
          minimum: 0
    Defaults:
      type: object
      description: What `POST /api/v1/projects` uses for each omitted field.
      required:
      - host
      - include_blog
      - include_docs
      - include_auth
      - include_google
      - include_github
      - include_stripe
      - include_api
      - include_storage
      - include_qdrant
      - sentry_features
      - posthog_features
      properties:
        host:
          type: string
        include_api:
          type: boolean
        include_auth:
          type: boolean
        include_blog:
          type: boolean
        include_docs:
          type: boolean
        include_github:
          type: boolean
        include_google:
          type: boolean
        include_mcp:
          type:
          - boolean
          - 'null'
        include_qdrant:
          type: boolean
        include_storage:
          type: boolean
        include_stripe:
          type: boolean
        posthog_features:
          type: array
          items:
            type: string
        sentry_features:
          type: array
          items:
            type: string
    Choice:
      type: object
      description: A hosting target for `host`.
      required:
      - value
      - label
      - description
      properties:
        description:
          type: string
        label:
          type: string
        value:
          type: string
          example: caprover
    Limits:
      type: object
      required:
      - name
      - slug
      - description
      properties:
        description:
          $ref: '#/components/schemas/MaxLength'
        name:
          $ref: '#/components/schemas/Range'
        slug:
          $ref: '#/components/schemas/SlugLimit'
    CreateRequest:
      type: object
      description: A new project. Only `name` is required; omitted fields take the new-project form's defaults (`GET /api/v1/options`). Unknown fields and capabilities are rejected with 422.
      required:
      - name
      properties:
        description:
          type: string
          description: For your own reference.
          maxLength: 1000
        host:
          type: string
          description: A `value` from the options' `hosts`.
          default: none
        include_api:
          type: boolean
          description: A JSON API for your users, with personal API keys and bearer authentication.
          default: true
        include_auth:
          type: boolean
          description: 'Accounts: sign-up with email verification, sign-in, passkeys, two-factor,

            settings, a dashboard and an admin panel. `false` generates a public site

            and leaves out the options that act for a signed-in user (`include_google`, `include_github`,

            `include_api`, `include_mcp`, `include_storage`, `include_stripe`,

            `include_qdrant`), whatever they say.'
          default: true
        include_blog:
          type: boolean
          description: Markdown posts and RSS.
          default: true
        include_docs:
          type: boolean
          description: Product documentation pages.
          default: true
        include_github:
          type: boolean
          description: 'Sign up and sign in with GitHub, connect GitHub to an existing account from

            settings, and confirm sensitive changes with GitHub for accounts without a

            password. Hidden until the owner configures their GitHub OAuth App.'
          default: true
        include_google:
          type: boolean
          description: 'Sign up and sign in with Google, connect Google to an existing account from

            settings, and confirm sensitive changes with Google for accounts without a

            password. Hidden until the owner configures their Google client.'
          default: true
        include_mcp:
          type:
          - boolean
          - 'null'
          description: 'An MCP server at `/mcp`. Omitted or null follows `include_api`, so

            turning the API off never needs a second field; `true` without the API is a 422.'
        include_qdrant:
          type: boolean
          description: 'Qdrant vector search scoped per user. Off by default: most products

            do not need a vector database.'
          default: false
        include_storage:
          type: boolean
          description: File storage for user uploads, with a profile picture upload as the example.
          default: true
        include_stripe:
          type: boolean
          description: Hosted Checkout, billing portal and webhooks.
          default: true
        name:
          type: string
          description: Replaces ShipRust in the generated project.
          example: Acme App
          maxLength: 64
          minLength: 2
        posthog_features:
          type: array
          items:
            type: string
          description: Keys from the options' `posthog_features`; all by default. An empty list turns PostHog off.
          default:
          - posthog-web
          - posthog-product
          - posthog-errors
          - posthog-logs
          - posthog-traces
        sentry_features:
          type: array
          items:
            type: string
          description: Keys from the options' `sentry_features`; all by default. An empty list turns Sentry off.
          default:
          - sentry-errors
          - sentry-traces
          - sentry-logs
          - sentry-metrics
          - sentry-replay
        slug:
          type: string
          description: 'Lowercase letters, digits and dashes, starting with a letter. Derived

            from `name` when empty. Unique per account.'
          example: acme-app
          maxLength: 40
          pattern: ^([a-z][a-z0-9-]*)?$
      additionalProperties: false
      example:
        host: caprover
        name: Acme App
        posthog_features: []
        sentry_features:
        - sentry-errors
    ProjectList:
      type: object
      required:
      - projects
      properties:
        projects:
          type: array
          items:
            $ref: '#/components/schemas/Project'
          description: Newest first.
  securitySchemes:
    api_key:
      type: http
      scheme: bearer
      bearerFormat: sr_<64 hex characters>
      description: A personal API key from Settings, or an OAuth 2.1 access token obtained through the authorization server described at /.well-known/oauth-authorization-server. Cookies are never accepted.