> ## Documentation Index
> Fetch the complete documentation index at: https://clearskies.cc/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Get an object's schema

> Lists the fields of one object type in your workspace, ordered by name, with what each
field supports. These are the fields Clearskies maintains; fields as your CRM names them,
custom fields included, are not served.


> [!NOTE]
>
> The Clearskies API is in beta and available on request. To turn it on for your workspace, email
> [support@clearskies.cc](mailto:support@clearskies.cc).


## OpenAPI

````yaml api-reference/openapi.yaml GET /v1/objects/{object}
openapi: 3.1.0
info:
  title: Clearskies Public API
  version: '1'
  description: >
    Read the accounts, calls, contacts and deals in your Context Graph, and the
    transcripts of

    your calls, from your own code.


    Every response is a JSON envelope. A success carries `ok: true` and the
    result in `data`; a

    failure carries `ok: false` and an `error` whose `code` is the value to
    branch on. Both carry

    `requestId`, which support resolves a report against.


    The fields available can differ between workspaces, so read an object's
    schema with

    `GET /v1/objects/{object}` before you query it. The schema lists every field
    you can select,

    filter, sort, group or measure, and the filter operators each one accepts.
servers:
  - url: https://api.clearskies.cc
security:
  - apiKey: []
tags:
  - name: Objects
    description: The object types the API serves, and the fields each one carries.
  - name: Records
    description: Query and aggregate the records of one object type.
  - name: Calls
    description: Read what was said on a call.
paths:
  /v1/objects/{object}:
    get:
      tags:
        - Objects
      summary: Get an object's schema
      description: >
        Lists the fields of one object type in your workspace, ordered by name,
        with what each

        field supports. These are the fields Clearskies maintains; fields as
        your CRM names them,

        custom fields included, are not served.
      operationId: getObjectSchema
      parameters:
        - $ref: '#/components/parameters/object'
      responses:
        '200':
          description: The object and its fields.
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessEnvelope'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/ObjectSchema'
              example:
                ok: true
                data:
                  name: deal
                  label: Deal
                  custom: false
                  fields:
                    - name: account
                      label: Account
                      type: reference
                      referenceTo: account
                      filterable: true
                      sortable: false
                      groupable: false
                      measurable: false
                      operators:
                        - equal
                        - notEqual
                        - isIn
                        - isNotIn
                        - isEmpty
                        - isNotEmpty
                    - name: amount
                      label: Amount
                      type: integer
                      filterable: true
                      sortable: true
                      groupable: true
                      measurable: true
                      operators:
                        - equal
                        - notEqual
                        - greaterThan
                        - greaterThanOrEqual
                        - lessThan
                        - lessThanOrEqual
                        - isIn
                        - isNotIn
                        - isEmpty
                        - isNotEmpty
                    - name: closeDate
                      label: Close Date
                      type: date
                      filterable: true
                      sortable: true
                      groupable: true
                      measurable: false
                      operators:
                        - equal
                        - notEqual
                        - before
                        - after
                        - isEmpty
                        - isNotEmpty
                requestId: 0199f2b0-7c41-7a3e-9d6c-2f5a1b8e4c07
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/TenantBlocked'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
components:
  parameters:
    object:
      name: object
      in: path
      required: true
      description: >-
        The object type. An unknown name is a `400`, and the message lists the
        valid ones.
      schema:
        $ref: '#/components/schemas/ObjectName'
  headers:
    X-RateLimit-Limit:
      description: >
        Requests the key can make in a burst. The rate-limit headers are sent on
        the responses

        that list them, while the rate limiter is reachable.
      schema:
        type: integer
    X-RateLimit-Remaining:
      description: Requests left in the current budget.
      schema:
        type: integer
    X-RateLimit-Reset:
      description: Seconds until the budget is full again.
      schema:
        type: integer
    X-Request-ID:
      description: >-
        Identifies this call, as `requestId` in the body does. Quote either to
        support.
      schema:
        type: string
    Retry-After:
      description: Seconds to wait before retrying.
      schema:
        type: integer
  schemas:
    SuccessEnvelope:
      type: object
      required:
        - ok
        - data
        - requestId
      properties:
        ok:
          type: boolean
          const: true
        data: {}
        requestId:
          type: string
          description: Identifies this call. Quote it when you contact support.
        traceId:
          type: string
          description: Present on a traced request.
    ObjectSchema:
      allOf:
        - $ref: '#/components/schemas/Object'
        - type: object
          required:
            - fields
          properties:
            fields:
              type: array
              items:
                $ref: '#/components/schemas/Field'
    ObjectName:
      type: string
      enum:
        - account
        - call
        - contact
        - deal
    Object:
      type: object
      required:
        - name
        - label
        - custom
      properties:
        name:
          $ref: '#/components/schemas/ObjectName'
        label:
          type: string
        custom:
          type: boolean
          description: True for an object type your CRM defines rather than a standard one.
    Field:
      type: object
      required:
        - name
        - label
        - type
        - filterable
        - sortable
        - groupable
        - measurable
        - operators
      properties:
        name:
          type: string
          description: >-
            The name to use for this field in records, filters, sort, `groupBy`
            and metrics.
        label:
          type: string
        type:
          $ref: '#/components/schemas/FieldType'
        referenceTo:
          allOf:
            - $ref: '#/components/schemas/ObjectName'
          description: >-
            For a reference field, the object type it points to. Filter it by
            that record's `id`.
        enumValues:
          type: array
          items:
            type: string
          description: For a picklist field, the values it can hold.
        filterable:
          type: boolean
          description: Whether the field can be used in `filters`.
        sortable:
          type: boolean
          description: Whether the field can be used in `sort`.
        groupable:
          type: boolean
          description: Whether the field can be used as `groupBy`.
        measurable:
          type: boolean
          description: Whether the field can be used in `metrics`.
        operators:
          type: array
          items:
            $ref: '#/components/schemas/FilterOperator'
          description: >-
            The operators `filters` accepts for this field. Empty when it is not
            filterable.
    ErrorEnvelope:
      type: object
      required:
        - ok
        - error
        - requestId
      properties:
        ok:
          type: boolean
          const: false
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              $ref: '#/components/schemas/ErrorCode'
            message:
              type: string
              description: >
                A diagnosis for a person to read. Its wording changes over time,
                so branch on

                `code`, not on this text.
        requestId:
          type: string
          description: Identifies this call. Quote it when you contact support.
        traceId:
          type: string
          description: Present on a traced request.
    FieldType:
      type: string
      description: >
        What a field holds. It decides which filter operators and values the
        field accepts, and

        how its value is written in a record: see the `…Value` schemas.
      enum:
        - text
        - textArray
        - slackText
        - timestamp
        - date
        - integer
        - duration
        - currency
        - reference
        - referenceArray
        - boolean
        - externalReferenceArray
    FilterOperator:
      type: string
      enum:
        - equal
        - notEqual
        - contains
        - greaterThan
        - greaterThanOrEqual
        - lessThan
        - lessThanOrEqual
        - before
        - after
        - isIn
        - isNotIn
        - isEmpty
        - isNotEmpty
    ErrorCode:
      type: string
      description: The value to branch on when a request fails.
      enum:
        - BAD_REQUEST
        - UNAUTHORIZED
        - TENANT_BLOCKED
        - NOT_FOUND
        - RATE_LIMITED
        - INTERNAL_ERROR
        - SERVICE_UNAVAILABLE
        - GATEWAY_TIMEOUT
  responses:
    BadRequest:
      description: >
        The API declined to run the request. The message names the member at
        fault by its JSON

        path and lists what that member accepts. Fix the request rather than
        retrying it.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            ok: false
            error:
              code: BAD_REQUEST
              message: >-
                filters[0].op "contains" is not an operator "createdAt" accepts.
                Valid operators: equal, notEqual, before, after, isEmpty,
                isNotEmpty.
            requestId: 0199f2b0-7c41-7a3e-9d6c-2f5a1b8e4c07
    Unauthorized:
      description: >
        The key was not accepted: it is missing, malformed, unknown or revoked;
        the person who

        created it has been deactivated or has left the workspace; or the
        workspace is inactive.

        Every case answers the same way, so check each when a key that worked
        starts failing.
      headers:
        WWW-Authenticate:
          schema:
            type: string
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    TenantBlocked:
      description: The key's workspace is blocked.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    RateLimited:
      description: >
        The key has spent its request budget, or has too many requests in
        flight. Wait for

        `Retry-After` seconds, then retry.
      headers:
        Retry-After:
          $ref: '#/components/headers/Retry-After'
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    InternalError:
      description: The request failed on our side. Quote `requestId` to support.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    ServiceUnavailable:
      description: >-
        The key could not be verified because a service it depends on did not
        answer. Retry.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    GatewayTimeout:
      description: >-
        The request ran past its deadline. Narrow the query with filters and
        retry.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: >
        An API key created under Context Graph → API keys in the app sidebar,
        sent as `Authorization: Bearer csk_…`.

        The key is checked on every request, so a revoked key fails on its next
        call.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.