openapi: 3.0.3
info:
  title: Zuper REST Assets Projects API
  description: The Zuper REST API provides programmatic access to the Zuper field service management platform. It covers jobs, scheduling, route optimization, customers, organizations, assets, inventory, purchase orders, invoices, proposals, quotes, timesheets, projects, properties, service tasks, service contracts, webhooks, and communications. Authentication uses API keys passed via the x-api-key header. Region-specific base URLs are discovered by POSTing to the accounts endpoint.
  version: 1.0.0
  contact:
    name: Zuper Developer Support
    url: https://developers.zuper.co/discuss
  x-api-evangelist-ratings:
    design: 7
    consistency: 7
    documentation: 8
servers:
- url: https://{dc_region}.zuperpro.com/api
  description: Region-specific API server (dc_region obtained from accounts endpoint)
  variables:
    dc_region:
      default: us1
      description: Data-center region identifier returned by the config endpoint
- url: https://accounts.zuperpro.com/api
  description: Accounts / configuration endpoint
security:
- ApiKeyAuth: []
tags:
- name: Projects
  description: Multi-job project management with phases, milestones, and dependencies
paths:
  /projects:
    get:
      summary: Get All Projects
      operationId: getAllProjects
      description: Retrieve a paginated list of projects.
      tags:
      - Projects
      parameters:
      - $ref: '#/components/parameters/PageParam'
      - $ref: '#/components/parameters/CountParam'
      responses:
        '200':
          description: Paginated list of projects
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'
    post:
      summary: Create Project
      operationId: createProject
      description: Create a new project.
      tags:
      - Projects
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                project_name:
                  type: string
                project_description:
                  type: string
                customer:
                  type: string
                start_date:
                  type: string
                  format: date-time
                end_date:
                  type: string
                  format: date-time
      responses:
        '200':
          description: Project created successfully
  /projects/{project_uid}:
    get:
      summary: Get Project Details
      operationId: getProjectDetails
      description: Retrieve details of a specific project.
      tags:
      - Projects
      parameters:
      - name: project_uid
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Project details
        '404':
          description: Not found
    put:
      summary: Update a Project
      operationId: updateProject
      description: Update an existing project.
      tags:
      - Projects
      parameters:
      - name: project_uid
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Project updated successfully
    delete:
      summary: Delete Project
      operationId: deleteProject
      description: Delete a project record.
      tags:
      - Projects
      parameters:
      - name: project_uid
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Project deleted successfully
components:
  parameters:
    CountParam:
      name: count
      in: query
      description: Number of records per page (max 1000)
      schema:
        type: integer
        default: 10
        maximum: 1000
    PageParam:
      name: page
      in: query
      description: Page number (1-based)
      schema:
        type: integer
        default: 1
  schemas:
    PaginatedResponse:
      type: object
      properties:
        type:
          type: string
        total_records:
          type: integer
        current_page:
          type: integer
        total_pages:
          type: integer
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key generated from Zuper Settings > Developer Hub > API Keys