openapi: 3.1.0
info:
  title: COR Attachments Ratecards API
  description: The COR API lets you integrate with projectcor.com applications using simple HTTP methods, in either XML or JSON formats, making this an ideal API for developing integrations with other softwares, external clients or mobile applications
  version: 1.0.0
servers:
- url: https://api.projectcor.com/v1
  description: Production server
security:
- bearerAuth: []
tags:
- name: Ratecards
paths:
  /projects/{project_id}/ratecard:
    get:
      tags:
      - Ratecards
      summary: Get project ratecard
      description: Returns the ratecard currently assigned to the project, or `null` if none is assigned. The ratecard defines pricing configurations (positions, rates, custom percentages) used when `estimated_by_hourly_rates` is enabled.
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Ratecard assigned to the project (or null)
          content:
            application/json:
              schema:
                nullable: true
                allOf:
                - $ref: '#/components/schemas/Ratecard'
  /ratecards:
    get:
      tags:
      - Ratecards
      summary: Get Ratecards
      description: Retrieves a paginated list of ratecards for the current company. Each ratecard defines pricing configurations such as positions, rates, and custom pricing percentages.
      parameters:
      - name: page
        in: query
        schema:
          type:
          - integer
          - boolean
          default: 1
        description: 'Page number (default: 1). Set to `false` to disable pagination.'
      - name: perPage
        in: query
        schema:
          type: integer
          default: 20
        description: 'Number of items per page (default: 20).'
      responses:
        '200':
          description: Paginated list of ratecards
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedRatecardsResponse'
    post:
      tags:
      - Ratecards
      summary: Create a Ratecard
      description: Creates a new ratecard for the current company.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RatecardInput'
            example:
              name: Custom Ratecard 1
              original_name: Custom Ratecard 1
              percent: 15
              currency_id: 1
              linked_to_base_price: false
              external_key: BILLING-RC-001
      responses:
        '200':
          description: Ratecard created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Ratecard'
              example:
                id: 51
                original_name: Custom Ratecard 1
                name: Custom Ratecard 1
                percent: 15
                company_id: 2336
                system: false
                created_at: '2025-12-15 00:24:41'
                updated_at: '2025-12-15 00:24:41'
                deleted_at: null
                external_key: BILLING-RC-001
                currency_id: 1
                linked_to_base_price: false
  /ratecards/{id}:
    put:
      tags:
      - Ratecards
      summary: Update a Ratecard
      description: Updates an existing ratecard by ID.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
        description: Ratecard ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RatecardUpdate'
            example:
              name: Custom Ratecard 1 (updated)
              original_name: Custom Ratecard 1
              percent: 20
              currency_id: 2
              linked_to_base_price: true
              external_key: BILLING-RC-001
      responses:
        '200':
          description: Ratecard updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Ratecard'
              example:
                id: 50
                original_name: Custom Ratecard 1
                name: Custom Ratecard 1 (updated)
                percent: 20
                company_id: 2336
                system: false
                created_at: '2025-12-15 00:24:41'
                updated_at: '2025-12-15 01:10:05'
                deleted_at: null
                external_key: BILLING-RC-001
                currency_id: 2
                linked_to_base_price: true
    delete:
      tags:
      - Ratecards
      summary: Delete a Ratecard
      description: Deletes (soft-delete) a ratecard by ID. Returns the deleted ratecard object with `deleted_at` timestamp set.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
        description: Ratecard ID
      responses:
        '200':
          description: Ratecard deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Ratecard'
              example:
                id: 50
                original_name: Custom Ratecard 1
                name: Custom Ratecard 1
                percent: 20
                company_id: 2336
                system: false
                created_at: '2025-12-15 00:24:41'
                updated_at: '2025-12-15 01:10:05'
                deleted_at: '2025-12-15 01:15:10'
                external_key: BILLING-RC-001
                currency_id: 2
                linked_to_base_price: true
        '204':
          description: Ratecard deleted successfully (no content)
components:
  schemas:
    PaginatedRatecardsResponse:
      type: object
      description: Paginated response for ratecards list
      properties:
        total:
          type:
          - string
          - integer
          description: Total number of ratecards
        perPage:
          type: integer
          description: Number of items per page
        page:
          type: integer
          description: Current page number
        lastPage:
          type: integer
          description: Last available page number
        data:
          type: array
          description: Array of ratecards for the current page
          items:
            $ref: '#/components/schemas/Ratecard'
    RatecardInput:
      type: object
      required:
      - name
      description: Input schema for creating a new ratecard
      properties:
        name:
          type: string
          description: Display name of the ratecard
        original_name:
          type: string
          description: Original/system name of the ratecard (usually same as name)
        percent:
          type: number
          description: Percentage applied by this ratecard (e.g., 0, 10, 15)
        currency_id:
          type: integer
          description: Associated currency ID. Defaults to the system's base currency if not specified.
        linked_to_base_price:
          type: boolean
          description: Whether the ratecard should be calculated based on base price
        external_key:
          type: string
          description: External key for integration with external systems
    Ratecard:
      type: object
      description: A ratecard defines pricing configurations for the company
      properties:
        id:
          type: integer
          description: Unique identifier for the ratecard
        name:
          type: string
          description: Display name of the ratecard
        original_name:
          type: string
          description: Original/system name of the ratecard
        percent:
          type: number
          description: Percentage applied by this ratecard
        company_id:
          type: integer
          description: Company ID that owns this ratecard
        system:
          type: boolean
          description: Whether this is a system-generated ratecard
        currency_id:
          type:
          - integer
          - 'null'
          description: Associated currency ID. Defaults to the system's base currency if not specified.
        linked_to_base_price:
          type: boolean
          description: Whether the ratecard is calculated based on base price
        external_key:
          type:
          - string
          - 'null'
          description: External key for integration with external systems
        created_at:
          type: string
          format: date-time
          description: Creation timestamp
        updated_at:
          type: string
          format: date-time
          description: Last update timestamp
        deleted_at:
          type:
          - string
          - 'null'
          format: date-time
          description: Deletion timestamp (soft delete)
    RatecardUpdate:
      type: object
      description: Input schema for updating an existing ratecard
      properties:
        name:
          type: string
          description: Display name of the ratecard
        original_name:
          type: string
          description: Original/system name of the ratecard
        percent:
          type: number
          description: Percentage applied by this ratecard
        currency_id:
          type: integer
          description: Associated currency ID. Defaults to the system's base currency.
        linked_to_base_price:
          type: boolean
          description: Whether the ratecard should be calculated based on base price
        external_key:
          type: string
          description: External key for integration with external systems
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    basicAuth:
      type: http
      scheme: basic