openapi: 3.1.0
info:
  title: Golden API v2 Entity API API
  version: '2.0'
servers:
- url: https://golden.com/
  description: Golden Public API V2
tags:
- name: Entity API
paths:
  /api/v2/public/entities/:
    get:
      operationId: public_api_entities_list
      summary: Get entities
      parameters:
      - name: cursor
        required: false
        in: query
        description: The pagination cursor value.
        schema:
          type: string
      - in: query
        name: entityTypeIds
        schema:
          type: string
        description: Comma separated Entity type ID(s) to restrict to (use schema API above to retrieve all available entity types).
        examples:
          CompanyAndPersonEntityTypes:
            value: 6,36
            summary: Company and Person entity types
      - in: query
        name: filterPredicateId
        schema:
          type: string
        description: Set a predicate filter by using filterPredicateId and filterValue query params. filterPredicateId is the ID of the predicate to be used. See predicate schema isFilterable field for supported predicate IDs.
        examples:
          WebsiteFilter:
            value: website
            summary: Website filter
      - in: query
        name: filterValue
        schema:
          type: string
        description: Set a predicate filter by using filterPredicateId and filterValue query params. filterValue is the value to be used for the filter.
        examples:
          WebsiteFilterValue:
            value: https://golden-support.com
            summary: Website filter value
      - in: query
        name: ids
        schema:
          type: string
        description: Comma separated entity IDs to restrict returned entities.
        examples:
          GoldenAndJudeGomilaEntities:
            value: 21,78
            summary: Golden and Jude Gomila entities
      - name: pageSize
        required: false
        in: query
        description: 'Number of results to return per page.

          The default value is 2 for Free Plan and 10 for Any Paid Plan.

          The maximum value is 100.'
        schema:
          type: integer
      - in: query
        name: predicateIds
        schema:
          type: string
        description: Comma separated Predicate ID(s) to restrict returned properties. Returns just the name property if not set.
        examples:
          WebsiteAndDateOfBirthPredicates:
            value: website,dateOfBirth
            summary: Website and Date Of Birth predicates
      tags:
      - Entity API
      security:
      - ApiKeyAuth: []
      responses:
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiEntitiesListErrorResponse400'
          description: ''
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse403'
              examples:
                PermissionDenied:
                  value:
                    type: client_error
                    errors:
                    - code: permission_denied
                      detail: You do not have permission to perform this action.
                      attr: null
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse404'
              examples:
                NotFound:
                  value:
                    type: client_error
                    errors:
                    - code: not_found
                      detail: Not found.
                      attr: null
          description: ''
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse429'
              examples:
                Throttled:
                  value:
                    type: client_error
                    errors:
                    - code: throttled
                      detail: Request was throttled.
                      attr: null
          description: ''
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse500'
              examples:
                APIException:
                  value:
                    type: server_error
                    errors:
                    - code: error
                      detail: A server error occurred.
                      attr: null
          description: ''
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedPublicAPIEntityList'
          description: ''
  /api/v2/public/entities/{id}/:
    get:
      operationId: public_api_entities_retrieve
      summary: Get entity by id
      parameters:
      - in: path
        name: id
        schema:
          type: integer
        description: A unique integer value identifying this entity.
        required: true
        examples:
          GoldenCompanyEntity:
            value: 21
            summary: Golden company entity
      - in: query
        name: predicateIds
        schema:
          type: string
        description: Comma separated Predicate ID(s) to restrict returned properties. Returns just the name property if not set.
        examples:
          WebsiteAndDateOfBirthPredicates:
            value: website,dateOfBirth
            summary: Website and Date Of Birth predicates
      tags:
      - Entity API
      security:
      - ApiKeyAuth: []
      responses:
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiEntitiesRetrieveErrorResponse400'
          description: ''
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse403'
              examples:
                PermissionDenied:
                  value:
                    type: client_error
                    errors:
                    - code: permission_denied
                      detail: You do not have permission to perform this action.
                      attr: null
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse404'
              examples:
                NotFound:
                  value:
                    type: client_error
                    errors:
                    - code: not_found
                      detail: Not found.
                      attr: null
          description: ''
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse429'
              examples:
                Throttled:
                  value:
                    type: client_error
                    errors:
                    - code: throttled
                      detail: Request was throttled.
                      attr: null
          description: ''
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse500'
              examples:
                APIException:
                  value:
                    type: server_error
                    errors:
                    - code: error
                      detail: A server error occurred.
                      attr: null
          description: ''
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAPIEntity'
          description: ''
components:
  schemas:
    Error429CodeEnum:
      enum:
      - throttled
      type: string
      description: '* `throttled` - Throttled'
    Error404:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/Error404CodeEnum'
        detail:
          type: string
        attr:
          type: string
          nullable: true
      required:
      - attr
      - code
      - detail
    Error403CodeEnum:
      enum:
      - permission_denied
      type: string
      description: '* `permission_denied` - Permission Denied'
    PublicAPIEntityPropertyInstance:
      type: object
      properties:
        value:
          allOf:
          - $ref: '#/components/schemas/PublicAPIEntityPropertyValue'
          description: 'Property Instance Value. The format depends on the predicate type.

            See the description for each option.'
        citations:
          type: array
          items:
            $ref: '#/components/schemas/PublicAPICitation'
          description: Arrays of citations
      required:
      - citations
      - value
    Error500CodeEnum:
      enum:
      - error
      type: string
      description: '* `error` - Error'
    Error403:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/Error403CodeEnum'
        detail:
          type: string
        attr:
          type: string
          nullable: true
      required:
      - attr
      - code
      - detail
    ErrorResponse429:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/Type5d3Enum'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error429'
      required:
      - errors
      - type
    ErrorResponse500TypeEnum:
      enum:
      - server_error
      type: string
      description: '* `server_error` - Server Error'
    ErrorResponse500:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/ErrorResponse500TypeEnum'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error500'
      required:
      - errors
      - type
    PublicAPICitation:
      type: object
      properties:
        title:
          type: string
          description: Citation Title
        url:
          type: string
          description: Citation URL value
      required:
      - title
      - url
    PublicApiEntitiesRetrieveErrorResponse400:
      oneOf:
      - $ref: '#/components/schemas/ParseErrorResponse'
      discriminator:
        propertyName: type
        mapping:
          client_error: '#/components/schemas/ParseErrorResponse'
    Error404CodeEnum:
      enum:
      - not_found
      type: string
      description: '* `not_found` - Not Found'
    ErrorResponse403:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/Type5d3Enum'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error403'
      required:
      - errors
      - type
    ParseError:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/ParseErrorCodeEnum'
        detail:
          type: string
        attr:
          type: string
          nullable: true
      required:
      - attr
      - code
      - detail
    PublicAPIEntityProperty:
      type: object
      properties:
        predicateId:
          type: string
          description: Property Predicate ID
        instances:
          type: array
          items:
            $ref: '#/components/schemas/PublicAPIEntityPropertyInstance'
          description: Array of Property Instances
      required:
      - instances
      - predicateId
    ErrorResponse404:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/Type5d3Enum'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error404'
      required:
      - errors
      - type
    ParseErrorCodeEnum:
      enum:
      - parse_error
      type: string
      description: '* `parse_error` - Parse Error'
    ParseErrorResponse:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/Type5d3Enum'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ParseError'
      required:
      - errors
      - type
    Error429:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/Error429CodeEnum'
        detail:
          type: string
        attr:
          type: string
          nullable: true
      required:
      - attr
      - code
      - detail
    PublicAPIEntity:
      type: object
      properties:
        id:
          type: integer
          description: Entity ID
        latestVersionId:
          type: integer
          description: ID of latest entity version
        properties:
          type: array
          items:
            $ref: '#/components/schemas/PublicAPIEntityProperty'
          readOnly: true
          description: Array of properties
      required:
      - id
      - latestVersionId
      - properties
    PublicApiEntitiesListErrorResponse400:
      oneOf:
      - $ref: '#/components/schemas/ParseErrorResponse'
      discriminator:
        propertyName: type
        mapping:
          client_error: '#/components/schemas/ParseErrorResponse'
    PaginatedPublicAPIEntityList:
      type: object
      properties:
        next:
          type: string
          nullable: true
          format: uri
          description: URL of next page
        previous:
          type: string
          nullable: true
          format: uri
          description: URL of previous page
        results:
          type: array
          items:
            $ref: '#/components/schemas/PublicAPIEntity'
    Error500:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/Error500CodeEnum'
        detail:
          type: string
        attr:
          type: string
          nullable: true
      required:
      - attr
      - code
      - detail
    PublicAPIEntityPropertyValue:
      oneOf:
      - type: integer
        description: Integer value. Used for int type.
      - type: number
        description: Number value. Used for float predicate types.
      - type: string
        description: 'String value. Used for text, url and date predicate types.

          For date type, the value is ISO-8601 formatted (YYYY-MM-DD, YYYY-MM, or YYYY).'
      - type: object
        properties:
          id:
            type: integer
            description: Entity ID
          properties:
            type: array
            items:
              type: object
            description: Array of properties. Same format as the root properties. Since this is a reference, it only includes the name property.
        description: Entity reference object. Used for entity and location types.
        required:
        - id
        - properties
      - type: object
        properties:
          gte:
            type: integer
            description: Range start numeric value (inclusive)
          lte:
            type: integer
            description: Range end numeric value (inclusive)
        description: Integer Range Value
        required:
        - gte
        - lte
      - type: object
        description: 'JSON object value. Used for json predicate type.

          For json type, the schema is predicate specific. See predicate schema resource for details.'
    Type5d3Enum:
      enum:
      - client_error
      type: string
      description: '* `client_error` - Client Error'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: apikey