Joocy API

openapi: 3.1.0
info:
  title: Joocy API
  version: '2026-11-13'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-11-13: 30 operation(s) read from 2 public documentation page(s) (each operation
    names its page in x-source). This is not the provider''s published contract; Joocy has published no machine-readable contract that the pipeline
    could find. Engine: local.'
  x-evidence-tiers:
    code-example: 0
    documentation: 30
    pages-with-code: 0
    pages-read: 2
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-11-13'
  x-generator: generate-contract-from-docs.py
  x-engine: local
  x-sources:
  - https://joo.cy/api/v1/guide
  - https://joo.cy/api/v1/skill
paths:
  /api/v1/decks:
    get:
      operationId: get_api_v1_decks
      tags:
      - Api
      summary: Interactive presentations. Every slide has a big-screen side and a phone side.
      x-source: https://joo.cy/api/v1/skill
      parameters:
      - name: q
        in: query
        required: false
        schema:
          type: string
        description: Search term to filter decks.
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiV1DecksResponse'
      x-evidence:
        kind: documentation
    post:
      operationId: post_api_v1_decks
      tags:
      - Api
      summary: Interactive presentations. Every slide has a big-screen side and a phone side.
      x-source: https://joo.cy/api/v1/skill
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV1DecksRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV1DecksResponse'
      x-evidence:
        kind: documentation
  /api/v1/decks/{id}:
    get:
      operationId: get_api_v1_decks_id
      tags:
      - Api
      summary: Interactive presentations. Every slide has a big-screen side and a phone side.
      x-source: https://joo.cy/api/v1/skill
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiV1DecksIdResponse'
      x-evidence:
        kind: documentation
  /api/v1/files/from-url:
    post:
      operationId: post_api_v1_files_from_url
      tags:
      - Api
      summary: Interactive presentations. Every slide has a big-screen side and a phone side.
      x-source: https://joo.cy/api/v1/skill
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV1FilesFromUrlRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV1FilesFromUrlResponse'
      x-evidence:
        kind: documentation
  /api/v1/guide:
    get:
      operationId: get_api_v1_guide
      tags:
      - Api
      summary: 'Joocy: the guide for agents'
      x-source: https://joo.cy/api/v1/guide
      parameters:
      - name: section
        in: query
        required: false
        schema:
          type: string
        description: Guide section name (e.g., "Patch ops")
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiV1GuideResponse'
      x-evidence:
        kind: documentation
  /catalog:
    get:
      operationId: get_catalog
      tags:
      - Catalog
      summary: The full machine‑readable list of everything you can use
      description: Provides catalog of layouts, phone views, etc.
      x-source: https://joo.cy/api/v1/guide
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCatalogResponse'
      x-evidence:
        kind: documentation
  /decks:
    get:
      operationId: get_decks
      tags:
      - Decks
      summary: 'Find it: GET /decks lists them all (or with ?q= for search)'
      description: Lists decks, optionally filtered by query
      x-source: https://joo.cy/api/v1/guide
      parameters:
      - name: q
        in: query
        required: false
        schema:
          type: string
        description: search term
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetDecksResponse'
      x-evidence:
        kind: documentation
    post:
      operationId: post_decks
      tags:
      - Decks
      summary: A new deck (whenever the request does not name one they have)
      description: Creates a new deck, returns 201 with deck data
      x-source: https://joo.cy/api/v1/guide
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostDecksRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostDecksResponse'
      x-evidence:
        kind: documentation
  /decks/{id}:
    get:
      operationId: get_decks_id
      tags:
      - Decks
      summary: GET /decks/{id} reads one deck
      description: Returns a single deck
      x-source: https://joo.cy/api/v1/guide
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetDecksIdResponse'
      x-evidence:
        kind: documentation
    patch:
      operationId: patch_decks_id
      tags:
      - Decks
      summary: Change it with PATCH /decks/{id} and a list of ops
      description: Applies patch ops to a deck
      x-source: https://joo.cy/api/v1/guide
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchDecksIdRequest'
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PatchDecksIdResponse'
      x-evidence:
        kind: documentation
    put:
      operationId: put_decks_id
      tags:
      - Decks
      summary: Replace it whole with PUT /decks/{id}
      description: Replaces the entire deck; 409 on stale version
      x-source: https://joo.cy/api/v1/guide
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PutDecksIdRequest'
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PutDecksIdResponse'
      x-evidence:
        kind: documentation
  /decks/{id}/duplicate:
    post:
      operationId: post_decks_id_duplicate
      tags:
      - Decks
      summary: Copies a deck they have, with its uploaded files, to make something new from it
      description: Duplicates an existing deck
      x-source: https://joo.cy/api/v1/guide
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostDecksIdDuplicateResponse'
      x-evidence:
        kind: documentation
  /decks/{id}/meta:
    put:
      operationId: put_decks_id_meta
      tags:
      - Decks
      summary: Move or star a deck.
      x-source: https://joo.cy/api/v1/guide
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PutDecksIdMetaRequest'
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /decks/{id}/present:
    post:
      operationId: post_decks_id_present
      tags:
      - Decks
      summary: Start or resume a live session.
      x-source: https://joo.cy/api/v1/guide
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /decks/{id}/sources/{sourceid}/apply:
    post:
      operationId: post_decks_id_sources_sourceid_apply
      tags:
      - Decks
      summary: Apply uploaded files to the deck.
      x-source: https://joo.cy/api/v1/guide
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: sourceid
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostDecksIdSourcesSourceidApplyRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /decks/{id}/sources/{sourceid}/files/index.html:
    put:
      operationId: put_decks_id_sources_sourceid_files_index_html
      tags:
      - Decks
      summary: Upload the HTML file for a coded deck.
      x-source: https://joo.cy/api/v1/guide
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: sourceid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /decks/{id}/sources/{sourceid}/files/{path}:
    delete:
      operationId: delete_decks_id_sources_sourceid_files_path
      tags:
      - Decks
      summary: Delete a file from a coded deck.
      x-source: https://joo.cy/api/v1/guide
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: sourceid
        in: path
        required: true
        schema:
          type: string
      - name: path
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /decks/{id}/validate:
    post:
      operationId: post_decks_id_validate
      tags:
      - Decks
      summary: POST /decks/{id}/validate checks a spec without saving
      description: Validates a deck spec, returns 422 with problems if invalid
      x-source: https://joo.cy/api/v1/guide
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostDecksIdValidateRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostDecksIdValidateResponse'
      x-evidence:
        kind: documentation
  /decks/{id}/versions:
    get:
      operationId: get_decks_id_versions
      tags:
      - Decks
      summary: GET /decks/{id}/versions lists saved versions
      description: Lists version history for a deck
      x-source: https://joo.cy/api/v1/guide
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetDecksIdVersionsResponse'
      x-evidence:
        kind: documentation
  /decks/{id}/versions/{v}/restore:
    post:
      operationId: post_decks_id_versions_v_restore
      tags:
      - Decks
      summary: POST /decks/{id}/versions/{v}/restore goes back to a previous version
      description: Restores a deck to a prior version
      x-source: https://joo.cy/api/v1/guide
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: v
        in: path
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostDecksIdVersionsVRestoreResponse'
      x-evidence:
        kind: documentation
  /files:
    post:
      operationId: post_files
      tags:
      - Files
      summary: Upload bytes for a file (e.g., picture)
      description: Direct file upload
      x-source: https://joo.cy/api/v1/guide
      parameters:
      - name: name
        in: query
        required: true
        schema:
          type: string
        description: filename, e.g., x.png
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostFilesRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostFilesResponse'
      x-evidence:
        kind: documentation
  /files/from-url:
    post:
      operationId: post_files_from_url
      tags:
      - Files
      summary: Copies a picture from a URL and returns a local URL
      description: Uploads an image by URL
      x-source: https://joo.cy/api/v1/guide
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostFilesFromUrlRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostFilesFromUrlResponse'
      x-evidence:
        kind: documentation
  /folders:
    get:
      operationId: get_folders
      tags:
      - Folders
      summary: List folders with deck counts.
      x-source: https://joo.cy/api/v1/guide
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
    post:
      operationId: post_folders
      tags:
      - Folders
      summary: Create a new folder.
      x-source: https://joo.cy/api/v1/guide
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostFoldersRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /folders/{id}:
    delete:
      operationId: delete_folders_id
      tags:
      - Folders
      summary: Remove a folder.
      x-source: https://joo.cy/api/v1/guide
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
    patch:
      operationId: patch_folders_id
      tags:
      - Folders
      summary: Rename a folder.
      x-source: https://joo.cy/api/v1/guide
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchFoldersIdRequest'
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /sessions:
    get:
      operationId: get_sessions
      tags:
      - Sessions
      summary: Interactive presentations. Every slide has a big-screen side and a phone side.
      x-source: https://joo.cy/api/v1/skill
      parameters:
      - name: deck
        in: query
        required: false
        schema:
          type: string
        description: Filter sessions by deck id
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /sessions/{sid}:
    get:
      operationId: get_sessions_sid
      tags:
      - Sessions
      summary: Get the session state and info.
      x-source: https://joo.cy/api/v1/guide
      parameters:
      - name: sid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /sessions/{sid}/control:
    post:
      operationId: post_sessions_sid_control
      tags:
      - Sessions
      summary: Drive a live session.
      x-source: https://joo.cy/api/v1/guide
      parameters:
      - name: sid
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostSessionsSidControlRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /sessions/{sid}/results:
    get:
      operationId: get_sessions_sid_results
      tags:
      - Sessions
      summary: Return every answer rolled up per question.
      x-source: https://joo.cy/api/v1/guide
      parameters:
      - name: sid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
components:
  schemas:
    GetApiV1DecksResponse:
      type: object
      properties:
        decks:
          type: array
          description: List of deck summaries.
    PostApiV1DecksRequest:
      type: object
      properties:
        spec:
          type: object
          description: Full deck specification.
      required:
      - spec
    PostApiV1DecksResponse:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        version:
          type: integer
        spec:
          type: object
    GetApiV1DecksIdResponse:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        version:
          type: integer
        spec:
          type: object
    PostApiV1FilesFromUrlRequest:
      type: object
      properties:
        url:
          type: string
          description: Source URL of the picture to import.
      required:
      - url
    PostApiV1FilesFromUrlResponse:
      type: object
      properties:
        url:
          type: string
          description: Internal URL of the uploaded file.
    GetApiV1GuideResponse:
      type: object
      properties:
        guide:
          type: object
          description: The guide content in JSON format
    GetCatalogResponse:
      type: object
      properties:
        layouts:
          type: object
        phoneViews:
          type: object
        cardBlocks:
          type: object
    GetDecksResponse:
      type: object
      properties:
        decks:
          type: array
          description: list of deck objects
    PostDecksRequest:
      type: object
      properties:
        spec:
          type: object
          description: the whole presentation spec
    PostDecksResponse:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        version:
          type: integer
        spec:
          type: object
    GetDecksIdResponse:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        version:
          type: integer
        spec:
          type: object
    PatchDecksIdRequest:
      type: object
      properties:
        ops:
          type: array
          description: JSON Patch operations (including merge, add, move, remove)
      required:
      - ops
    PatchDecksIdResponse:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        version:
          type: integer
        spec:
          type: object
    PutDecksIdRequest:
      type: object
      properties:
        spec:
          type: object
        version:
          type: integer
          description: the version you read
      required:
      - spec
      - version
    PutDecksIdResponse:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        version:
          type: integer
        spec:
          type: object
    PostDecksIdDuplicateResponse:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        version:
          type: integer
        spec:
          type: object
    PutDecksIdMetaRequest:
      type: object
      properties:
        folder:
          type: string
          description: Folder ID to move the deck into, or null
        starred:
          type: boolean
          description: Whether to star the deck
    PostDecksIdSourcesSourceidApplyRequest:
      type: object
      properties:
        entry:
          type: string
          description: File to apply, e.g., "index.html"
        scan:
          type: boolean
          description: Whether to scan the file for slides
      required:
      - entry
      - scan
    PostDecksIdValidateRequest:
      type: object
      properties:
        spec:
          type: object
      required:
      - spec
    PostDecksIdValidateResponse:
      type: object
      properties:
        valid:
          type: boolean
    GetDecksIdVersionsResponse:
      type: object
      properties:
        versions:
          type: array
          description: list of version objects
    PostDecksIdVersionsVRestoreResponse:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        version:
          type: integer
        spec:
          type: object
    PostFilesRequest:
      type: object
      properties:
        file:
          type: string
          description: file bytes
      required:
      - file
    PostFilesResponse:
      type: object
      properties:
        url:
          type: string
          description: local asset path
    PostFilesFromUrlRequest:
      type: object
      properties:
        url:
          type: string
          description: source image URL
      required:
      - url
    PostFilesFromUrlResponse:
      type: object
      properties:
        url:
          type: string
          description: local asset path like /a/...
    PostFoldersRequest:
      type: object
      properties:
        name:
          type: string
          description: Folder name
      required:
      - name
    PatchFoldersIdRequest:
      type: object
      properties:
        name:
          type: string
          description: New folder name
      required:
      - name
    PostSessionsSidControlRequest:
      type: object
      properties:
        t:
          type: string
          description: Command type, e.g., "nav", "goto", "control"
        dir:
          type: string
          description: Direction for nav commands, e.g., "next"
        slide:
          type: string
          description: Slide ID for goto commands
        step:
          type: integer
          description: Step number for goto commands
        action:
          type: string
          description: Action for control commands, e.g., "reveal"
        iid:
          type: string
          description: Interaction ID for control actions
      required:
      - t
tags:
- name: Api
- name: Catalog
- name: Decks
- name: Files
- name: Folders
- name: Sessions