openapi: 3.0.3
info:
  title: Juro API
  description: >-
    The Juro API (v3) programmatically drives contract automation and contract
    lifecycle management (CLM) on the Juro platform. External systems can initiate
    contracts from Juro templates, upload existing PDFs as contracts, read and
    update contract smart fields, send contracts for e-signature, download signed
    PDFs, and subscribe to contract lifecycle events via webhooks. All requests are
    authenticated with an `x-api-key` header. API access is plan-gated - it is
    included with a Juro subscription and enabled through your Customer Success
    Manager. A sandbox environment is available at https://api-sandbox.juro.io/v3.

    Endpoints under Contracts, Templates, and Signatures are confirmed from Juro's
    public API reference (api-docs.juro.com). The Webhooks management endpoints are
    modeled from Juro's help-center guidance; webhook subscriptions are primarily
    configured in the Juro app (Settings > Integrations > Webhooks). Operations
    marked `x-endpoint-modeled: true` were not confirmed in the public reference at
    the time of review.
  version: '3.0'
  contact:
    name: Juro
    url: https://juro.com
  termsOfService: https://juro.com/terms/api-terms
servers:
  - url: https://api.juro.com/v3
    description: Production
  - url: https://api-sandbox.juro.io/v3
    description: Sandbox
security:
  - apiKeyAuth: []
tags:
  - name: Health
    description: API status and key validity.
  - name: Contracts
    description: Create, read, update, delete, and upload contracts.
  - name: Templates
    description: List and retrieve contract templates.
  - name: Signatures
    description: Send contracts for e-signature and apply signatures.
  - name: Webhooks
    description: Subscribe to contract lifecycle events (modeled).
paths:
  /health:
    get:
      operationId: getHealth
      tags:
        - Health
      summary: Check API status
      description: Returns the API status and confirms the supplied API key is valid.
      responses:
        '200':
          description: The API is healthy and the key is valid.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /templates:
    get:
      operationId: listTemplates
      tags:
        - Templates
      summary: List templates
      description: Returns a paginated list of all contract templates accessible to the API key holder.
      parameters:
        - $ref: '#/components/parameters/Skip'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: A paginated list of templates.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /templates/{template_id}:
    get:
      operationId: getTemplate
      tags:
        - Templates
      summary: Retrieve a template
      description: Retrieves a single template by ID, including its smart fields.
      parameters:
        - $ref: '#/components/parameters/TemplateId'
      responses:
        '200':
          description: The requested template.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /contracts:
    get:
      operationId: listContracts
      tags:
        - Contracts
      summary: List contracts
      description: Returns a paginated list of all contracts accessible to the API key holder.
      parameters:
        - $ref: '#/components/parameters/Skip'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: A paginated list of contracts.
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createContract
      tags:
        - Contracts
      summary: Create a contract from a template
      description: Creates a new contract from a Juro template, supplying values for the template smart fields.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: The created contract.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /contracts/upload:
    post:
      operationId: uploadContract
      tags:
        - Contracts
      summary: Upload a PDF as a contract
      description: Creates a contract by uploading an existing PDF document.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '201':
          description: The created contract.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /contracts/{contract_id}:
    get:
      operationId: getContract
      tags:
        - Contracts
      summary: Retrieve a contract
      description: Retrieves a single contract by ID, including its smart fields and current state.
      parameters:
        - $ref: '#/components/parameters/ContractId'
      responses:
        '200':
          description: The requested contract.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateContract
      tags:
        - Contracts
      summary: Update a contract
      description: Updates a contract's properties and smart-field values.
      parameters:
        - $ref: '#/components/parameters/ContractId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: The updated contract.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteContract
      tags:
        - Contracts
      summary: Delete a contract
      description: Deletes a contract by ID.
      parameters:
        - $ref: '#/components/parameters/ContractId'
      responses:
        '204':
          description: The contract was deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /contracts/{contract_id}/pdf/binary:
    get:
      operationId: getContractPdf
      tags:
        - Contracts
      summary: Download contract PDF
      description: Downloads the generated or signed contract as a binary PDF.
      parameters:
        - $ref: '#/components/parameters/ContractId'
      responses:
        '200':
          description: The contract PDF.
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /contracts/{contract_id}/sign:
    post:
      operationId: signContract
      tags:
        - Signatures
      summary: Sign a contract
      description: Applies a signature to a contract on behalf of the API key holder's signing side.
      parameters:
        - $ref: '#/components/parameters/ContractId'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: The contract signature result.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /contracts/{contract_id}/signing-request/{signing_side_uid}:
    post:
      operationId: sendSigningRequest
      tags:
        - Signatures
      summary: Send a contract for signing
      description: Sends a signing request to a signing side of the contract.
      parameters:
        - $ref: '#/components/parameters/ContractId'
        - $ref: '#/components/parameters/SigningSideUid'
      responses:
        '200':
          description: The signing request was sent.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /contracts/{contract_id}/signing-request/{signing_side_uid}/signatures/{signature_uid}:
    post:
      operationId: sendSigningRequestToSignatory
      tags:
        - Signatures
      summary: Send a signing request to a signatory
      description: Sends a signing request to a specific signatory within a signing side.
      parameters:
        - $ref: '#/components/parameters/ContractId'
        - $ref: '#/components/parameters/SigningSideUid'
        - $ref: '#/components/parameters/SignatureUid'
      responses:
        '200':
          description: The signing request was sent to the signatory.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /webhooks:
    get:
      operationId: listWebhooks
      tags:
        - Webhooks
      summary: List webhooks (modeled)
      description: >-
        Lists the webhook subscriptions for a team. Modeled from Juro help-center
        guidance; webhooks are primarily managed in the Juro app.
      x-endpoint-modeled: true
      responses:
        '200':
          description: A list of webhook subscriptions.
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createWebhook
      tags:
        - Webhooks
      summary: Create a webhook (modeled)
      description: >-
        Registers a webhook subscription for contract lifecycle events. Modeled
        from Juro help-center guidance (body includes teamId, title, url, isEnabled,
        auth, and events). Not confirmed in the public API reference.
      x-endpoint-modeled: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                teamId:
                  type: string
                title:
                  type: string
                url:
                  type: string
                  format: uri
                isEnabled:
                  type: boolean
                auth:
                  type: object
                  description: Basic auth credentials or HMAC-SHA256 signing configuration.
                events:
                  type: array
                  items:
                    type: string
                    enum:
                      - contract.created
                      - contract.deleted
                      - contract.edit
                      - contract.commented
                      - contract.comment.deleted
                      - contract.viewed
                      - contract.pdf_generated
                      - contract.sent_link_to_counterparty
                      - contract.signed
                      - contract.approval_requested
                      - contract.approval_in_progress
                      - contract.approval_process_finished
                      - contract.approval_denied
                      - contract.approval_request_cancelled
              required:
                - url
                - events
      responses:
        '201':
          description: The created webhook subscription.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /webhooks/{webhook_id}:
    delete:
      operationId: deleteWebhook
      tags:
        - Webhooks
      summary: Delete a webhook (modeled)
      description: >-
        Deletes a webhook subscription. Modeled from Juro help-center guidance;
        not confirmed in the public API reference.
      x-endpoint-modeled: true
      parameters:
        - name: webhook_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: The webhook was deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key generated in the Juro app under Settings > Integrations > API. Sent as the `x-api-key` request header.
  parameters:
    Skip:
      name: skip
      in: query
      required: false
      description: Number of records to skip for pagination.
      schema:
        type: integer
        default: 0
    Limit:
      name: limit
      in: query
      required: false
      description: Number of records to return (max 200).
      schema:
        type: integer
        default: 50
        maximum: 200
    ContractId:
      name: contract_id
      in: path
      required: true
      description: The unique ID of the contract.
      schema:
        type: string
    TemplateId:
      name: template_id
      in: path
      required: true
      description: The unique ID of the template.
      schema:
        type: string
    SigningSideUid:
      name: signing_side_uid
      in: path
      required: true
      description: The UID of the signing side.
      schema:
        type: string
    SignatureUid:
      name: signature_uid
      in: path
      required: true
      description: The UID of the signatory's signature.
      schema:
        type: string
  responses:
    Unauthorized:
      description: The API key is missing or invalid.
    NotFound:
      description: The requested resource was not found.