openapi: 3.0.3
info:
  title: Aurora Solar Agreements Designs API
  description: 'The Aurora API lets you build apps and integrations on the Aurora Solar platform for solar sales and design. It is a tenant-scoped REST API: every resource lives under /tenants/{tenant_id}. Requests are authenticated with an API-key bearer token (Standard keys prefixed `sk_`, Restricted keys prefixed `rk_`; `sand_`/`prod_` denote the environment) passed as `Authorization: Bearer <token>`. The current API version is v2024.05, selected via the `Aurora-Version` request header.


    Scope note: A handful of paths in this document are confirmed directly against Aurora''s public reference (List Projects, Create Design Request, Create Webhook). The remaining paths are HONESTLY MODELED from Aurora''s published operation catalog (docs.aurorasolar.com/llms.txt) following the same `/tenants/{tenant_id}/<resource>` convention; exact path segments for modeled operations should be reconciled against the live reference, which is partially gated. Modeled operations carry `x-modeled: true`.'
  version: v2024.05
  contact:
    name: Aurora Solar Developer Platform
    url: https://docs.aurorasolar.com
  license:
    name: Proprietary
    url: https://aurorasolar.com/terms-of-service/
servers:
- url: https://api.aurorasolar.com
  description: Production
- url: https://api-sandbox.aurorasolar.com
  description: Sandbox
security:
- bearerAuth: []
tags:
- name: Designs
  description: Design requests and PV designs with simulation output.
paths:
  /tenants/{tenant_id}/design_requests:
    parameters:
    - $ref: '#/components/parameters/TenantId'
    post:
      operationId: createDesignRequest
      tags:
      - Designs
      summary: Create a design request
      description: Submits an asynchronous design request for a project. If latitude and longitude are omitted, the project's coordinates are used. Poll the design request or subscribe to a webhook for completion.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DesignRequestInput'
      responses:
        '202':
          description: The accepted design request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DesignRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimited'
  /tenants/{tenant_id}/design_requests/{design_request_id}:
    parameters:
    - $ref: '#/components/parameters/TenantId'
    - name: design_request_id
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: retrieveDesignRequest
      tags:
      - Designs
      summary: Retrieve a design request
      description: Retrieves the status and result of a design request.
      x-modeled: true
      responses:
        '200':
          description: The design request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DesignRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: acceptDesignRequest
      tags:
      - Designs
      summary: Accept a design request
      description: Accepts a completed design request, producing a design.
      x-modeled: true
      responses:
        '200':
          description: The resulting design.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Design'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /tenants/{tenant_id}/designs:
    parameters:
    - $ref: '#/components/parameters/TenantId'
    get:
      operationId: listDesigns
      tags:
      - Designs
      summary: List designs
      description: Lists designs for the tenant, optionally filtered by project.
      x-modeled: true
      parameters:
      - name: project_id
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: A list of designs.
          content:
            application/json:
              schema:
                type: object
                properties:
                  designs:
                    type: array
                    items:
                      $ref: '#/components/schemas/Design'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createDesign
      tags:
      - Designs
      summary: Create a design
      description: Creates a design for a project.
      x-modeled: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DesignInput'
      responses:
        '201':
          description: The created design.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Design'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /tenants/{tenant_id}/designs/{design_id}:
    parameters:
    - $ref: '#/components/parameters/TenantId'
    - $ref: '#/components/parameters/DesignId'
    get:
      operationId: retrieveDesign
      tags:
      - Designs
      summary: Retrieve a design
      description: Retrieves a design, including arrays, components, and pricing references.
      x-modeled: true
      responses:
        '200':
          description: The requested design.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Design'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /tenants/{tenant_id}/designs/{design_id}/summary:
    parameters:
    - $ref: '#/components/parameters/TenantId'
    - $ref: '#/components/parameters/DesignId'
    get:
      operationId: retrieveDesignSummary
      tags:
      - Designs
      summary: Retrieve design summary
      description: Retrieves a design summary including system size, annual production, and performance-simulation outputs.
      x-modeled: true
      responses:
        '200':
          description: The design summary.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    Error:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
              title:
                type: string
              detail:
                type: string
    DesignInput:
      type: object
      required:
      - project_id
      properties:
        project_id:
          type: string
        name:
          type: string
    Design:
      allOf:
      - $ref: '#/components/schemas/DesignInput'
      - type: object
        properties:
          id:
            type: string
            format: uuid
          system_size_kw:
            type: number
            format: double
          annual_production_kwh:
            type: number
            format: double
          arrays:
            type: array
            items:
              type: object
              additionalProperties: true
          created_at:
            type: string
            format: date-time
    DesignRequestInput:
      type: object
      required:
      - project_id
      properties:
        project_id:
          type: string
        design_mode:
          type: string
          description: Design generation mode (for example manual or auto_designer).
          enum:
          - manual
          - auto_designer
        latitude:
          type: number
          format: double
        longitude:
          type: number
          format: double
    DesignRequest:
      allOf:
      - $ref: '#/components/schemas/DesignRequestInput'
      - type: object
        properties:
          id:
            type: string
            format: uuid
          status:
            type: string
            enum:
            - pending
            - in_progress
            - completed
            - failed
          design_id:
            type: string
            format: uuid
          created_at:
            type: string
            format: date-time
  parameters:
    DesignId:
      name: design_id
      in: path
      required: true
      description: The design ID.
      schema:
        type: string
    TenantId:
      name: tenant_id
      in: path
      required: true
      description: The tenant (organization) ID that owns the resource.
      schema:
        type: string
  responses:
    ValidationError:
      description: The request payload failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid bearer token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Rate limit exceeded (default 90 requests/minute). Inspect the `Retry-After` response header for when to retry.
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'API-key bearer token. Standard keys are prefixed `sk_`, Restricted keys `rk_`; `sand_`/`prod_` denote sandbox vs production. Passed as `Authorization: Bearer <token>`.'