openapi: 3.0.0
info:
  title: Entities API
  version: 1.0.0
servers:
  - url: https://api.useautumn.com/v1
security:
  - bearerAuth: []
paths:
  /customers/{customer_id}/entities:
    post:
      summary: Create a new entity
      operationId: createEntity
      security:
        - bearerAuth: []
      parameters:
        - name: customer_id
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier of the customer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateEntityRequest"
      responses:
        "201":
          description: ""
      x-code-samples:
        - lang: typescript
          label: single entity
          source: |
            import { Autumn as autumn } from 'autumn-js';

            const entity = await autumn.entities.create('user_123', {
              feature_id: 'seats',
              id: 'seat_456',
              name: 'Brandon Yeo'
            });

        - lang: typescript
          label: multiple entities
          source: |
            import { Autumn as autumn } from 'autumn-js';

            const entities = await autumn.entities.create('user_123',
            [
              {
                feature_id: 'seats',
                id: 'seat_456',
                name: 'Brandon Yeo'
              },
              {
                feature_id: 'seats',
                id: 'seat_789',
                name: 'John Yeo'
              }
            ]);

        - lang: curl
          label: single entity
          source: |
            curl -X POST 'https://api.useautumn.com/v1/customers/user_123/entities' \
            -H 'Authorization: Bearer am_sk_1234567890' \
            -H 'Content-Type: application/json' \
            -d '{
              "feature_id": "seats",
              "id": "seat_456",
              "name": "Brandon Yeo"
            }'

        - lang: curl
          label: multiple entities
          source: |
            curl -X POST 'https://api.useautumn.com/v1/customers/user_123/entities' \
            -H 'Authorization: Bearer am_sk_1234567890' \
            -H 'Content-Type: application/json' \
            -d '[
              {
                "feature_id": "seats",
                "id": "seat_456",
                "name": "Brandon Yeo"
              },
              {
                "feature_id": "seats",
                "id": "seat_789",
                "name": "John Yeo"
            }]'

        - lang: python
          label: single entity
          source: |
            import asyncio
            from autumn import Autumn

            autumn = Autumn('am_sk_1234567890')

            async def main():
                entity = await autumn.entities.create(
                    customer_id='user_123',
                    id='seat_456',
                    feature_id='seats',
                    name='Brandon Yeo'
                )

            asyncio.run(main())

  /customers/{customer_id}/entities/{entity_id}:
    get:
      summary: Get an entity
      operationId: getEntity
      security:
        - bearerAuth: []
      parameters:
        - name: customer_id
          in: path
          required: true
          schema:
            type: string
          description: Your unique identifier for the customer
        - name: entity_id
          in: path
          required: true
          schema:
            type: string
          description: Your unique identifier of the entity (eg, a seat ID)
        - name: expand
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
              enum: ["invoices"]
          style: form
          explode: false
          description: Array of additional data to include in the entity response. Currently supports "invoices"
      responses:
        "200":
          description: Entity retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Entity"
        "404":
          description: Entity not found
      x-code-samples:
        - lang: typescript
          source: |
            const { data } = await autumn.entities.get('user_123', 'ent_1');
        - lang: python
          source: |
            entity = await autumn.entities.get(customer_id='user_123', entity_id='ent_1')
        - lang: curl
          source: |
            curl -X GET 'https://api.useautumn.com/v1/customers/user_123/entities/ent_1' \
            -H 'Authorization: Bearer am_sk_1234567890'

    delete:
      summary: Delete an entity
      operationId: deleteEntity
      security:
        - bearerAuth: []
      parameters:
        - name: customer_id
          in: path
          required: true
          schema:
            type: string
          description: Your unique identifier for the customer
        - name: entity_id
          in: path
          required: true
          schema:
            type: string
          description: Your unique identifier of the entity (eg, a seat ID)
      responses:
        "200":
          description: ""
      x-code-samples:
        - lang: typescript
          source: |
            await autumn.entities.delete(customer_id='user_123', entity_id='seat_456');
        - lang: python
          source: |
            import asyncio
            from autumn import Autumn

            autumn = Autumn('am_sk_1234567890')

            async def main():
                await autumn.entities.delete(customer_id='user_123', entity_id='seat_456')

            asyncio.run(main())

components:
  schemas:
    CreateEntityRequest:
      type: array
      items:
        type: object
        required:
          - id
          - feature_id
          - name
        properties:
          id:
            type: string
            description: Your unique identifier for the entity (eg, a seat ID)
          feature_id:
            type: string
            description: The feature ID associated with this entity (eg, seats). When an entity is created, a usage event will be recorded for this feature.
          name:
            type: string
            description: A name or identifier for the entity (e.g., an email address)

    Entity:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the entity
        name:
          type: string
          description: The name of the entity
        customer_id:
          type: string
          description: The customer ID this entity belongs to
        created_at:
          type: integer
          format: int64
          description: Unix timestamp when the entity was created
        env:
          type: string
          description: The environment (sandbox/live)
        products:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
              group:
                type: string
                nullable: true
              status:
                type: string
              canceled_at:
                type: integer
                format: int64
                nullable: true
              started_at:
                type: integer
                format: int64
              is_default:
                type: boolean
              is_add_on:
                type: boolean
              version:
                type: integer
              current_period_start:
                type: integer
                format: int64
              current_period_end:
                type: integer
                format: int64
              entity_id:
                type: string
              items:
                type: array
                items:
                  type: object
              quantity:
                type: integer
          description: Products associated with this entity
        features:
          type: object
          additionalProperties:
            type: object
            properties:
              id:
                type: string
              type:
                type: string
              name:
                type: string
              interval:
                type: string
              interval_count:
                type: integer
              unlimited:
                type: boolean
              balance:
                type: number
              usage:
                type: number
              included_usage:
                type: number
              next_reset_at:
                type: integer
                format: int64
              overage_allowed:
                type: boolean
          description: Features associated with this entity
        invoices:
          type: array
          items:
            type: object
            properties:
              product_ids:
                type: array
                items:
                  type: string
              stripe_id:
                type: string
              status:
                type: string
              total:
                type: number
              currency:
                type: string
              created_at:
                type: integer
                format: int64
              hosted_invoice_url:
                type: string
          description: Invoices for this entity (only included when expand=invoices)

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer