openapi: 3.0.1
info:
  title: Sentera FieldAgent API
  description: >-
    The Sentera FieldAgent API is a GraphQL API, not a resource-oriented REST
    API. All operations - queries and mutations covering fields, surveys,
    flight tasks, imagery, mosaics, analytics, orders, and organizations - are
    sent as GraphQL documents to a single HTTP endpoint
    (https://api.sentera.com/graphql) using POST (GET is also supported).

    Because there are no per-resource REST paths to enumerate, this OpenAPI
    document models only the one real HTTP transport endpoint that fronts the
    GraphQL schema. The full operation catalog (30+ queries such as `field`,
    `fields`, `survey`, `surveys`, `task`, `tasks`, `analytic`, `order`,
    `orders`, `organization`, and 80+ mutations such as `create_field`,
    `place_order`, and webhook subscriptions) is defined by the GraphQL schema
    rather than by HTTP paths; see graphql/sentera-graphql.md and the upstream
    GraphQL reference at https://api.sentera.com/api/docs/operation/query/index.html.

    No fabricated REST endpoints are included.
  termsOfService: https://sentera.com/terms-of-use/
  contact:
    name: Sentera Support
    url: https://support.senterasensors.com/home/fieldagent
  version: '1.0'
servers:
  - url: https://api.sentera.com
    description: Sentera FieldAgent GraphQL endpoint host
paths:
  /graphql:
    post:
      operationId: executeGraphQL
      tags:
        - GraphQL
      summary: Execute a FieldAgent GraphQL query or mutation
      description: >-
        Single GraphQL endpoint for all FieldAgent operations. Send a GraphQL
        query or mutation in the request body. Requires a Sentera auth_token
        supplied as a Bearer token in the Authorization header. Returns a
        standard GraphQL response envelope with `data` and/or `errors`.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GraphQLRequest'
            examples:
              listFields:
                summary: Query fields in an organization
                value:
                  query: >-
                    query { fields(owner_id: "ORG_SENTERA_ID") { results { id name } } }
              createField:
                summary: Create a field
                value:
                  query: >-
                    mutation CreateField($name: String!) { create_field(name: $name) { field { id name } } }
                  variables:
                    name: North 40
      responses:
        '200':
          description: >-
            GraphQL response. Note that GraphQL returns HTTP 200 even when the
            response carries field-level `errors`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphQLResponse'
        '401':
          description: Missing or invalid Sentera auth_token.
    get:
      operationId: executeGraphQLGet
      tags:
        - GraphQL
      summary: Execute a FieldAgent GraphQL query via GET
      description: >-
        GraphQL queries may also be issued as a GET request with the `query`
        (and optional `variables`) passed as query-string parameters. Requires
        the same Bearer auth_token.
      security:
        - bearerAuth: []
      parameters:
        - name: query
          in: query
          required: true
          description: URL-encoded GraphQL query document.
          schema:
            type: string
        - name: variables
          in: query
          required: false
          description: URL-encoded JSON object of GraphQL variables.
          schema:
            type: string
      responses:
        '200':
          description: GraphQL response envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphQLResponse'
        '401':
          description: Missing or invalid Sentera auth_token.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Sentera auth_token presented as `Authorization: Bearer <auth_token>`.
        See the Authentication and Authorization documentation for obtaining a
        token.
  schemas:
    GraphQLRequest:
      type: object
      required:
        - query
      properties:
        query:
          type: string
          description: The GraphQL query or mutation document.
        operationName:
          type: string
          description: Name of the operation to run when the document defines several.
        variables:
          type: object
          additionalProperties: true
          description: Key/value map of GraphQL variables.
    GraphQLResponse:
      type: object
      properties:
        data:
          type: object
          additionalProperties: true
          nullable: true
          description: Result data keyed by the requested fields.
        errors:
          type: array
          description: GraphQL errors, present when one or more fields fail to resolve.
          items:
            type: object
            properties:
              message:
                type: string
              path:
                type: array
                items:
                  type: string
              locations:
                type: array
                items:
                  type: object
                  properties:
                    line:
                      type: integer
                    column:
                      type: integer