Oneprofile App Listings API

openapi: 3.2.0
info:
  contact:
    email: support@getoneprofile.ai
    name: Oneprofile Support
  description: REST API reference for Oneprofile, the GTM data layer for your CRM. Manage tables, enrichments, and integrations. Authenticate with an API key to get started.
  termsOfService: https://www.getoneprofile.ai/terms
  title: Reference | Oneprofile App Listings API
  version: 1.0.42765316646
tags:
- description: Endpoints for the generic OAuth install/claim app-listings engine.
  name: app-listings
paths:
  /app-listings/connections/{connection_id}/claim/:
    post:
      description: Re-authorize an existing integration in place from a switch/reconnect OAuth grant. The target integration and intent are read from the pending connection (bound server-side from the OAuth state), so the grant can only re-authorize the integration it was started for. Preserves every sync, schedule, mapping, alert, and history row on the connection. With dry_run, the connection and the integration are checked and left as they are; the new grant is not tried against the vendor.
      operationId: claim_onto_existing
      parameters:
      - in: path
        name: connection_id
        required: true
        schema:
          maxLength: 255
          minLength: 1
          title: Connection Id
          type: string
      - description: Check the claim and answer as the real call would, changing nothing.
        in: query
        name: dry_run
        required: false
        schema:
          default: false
          description: Check the claim and answer as the real call would, changing nothing.
          title: Dry Run
          type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppListingClaimOntoExistingResponseSchema'
          description: Successful Response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'
          description: Pending connection or target not found
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntityResponse'
          description: Invalid request made to the API.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
          description: Internal server error.
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
          description: Bad gateway error.
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
          description: Service unavailable.
      security:
      - APIKeyHeader: []
      - HTTPBearer: []
      summary: Finalize a switch/reconnect onto an existing integration
      tags:
      - app-listings
  /app-listings/connections/{connection_id}/config/:
    get:
      description: Return the tenant/region/login config the engine captured for a pending OAuth connection (e.g. Salesforce login_url), so the create wizard can show the customer (read-only) the workspace they linked. Empty for one-click listings.
      operationId: get_connection_config
      parameters:
      - in: path
        name: connection_id
        required: true
        schema:
          maxLength: 255
          minLength: 1
          title: Connection Id
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppListingConnectionConfigResponseSchema'
          description: Successful Response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'
          description: Pending connection not found
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntityResponse'
          description: Invalid request made to the API.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
          description: Internal server error.
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
          description: Bad gateway error.
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
          description: Service unavailable.
      security:
      - APIKeyHeader: []
      - HTTPBearer: []
      summary: Get a pending connection's captured connect-time config
      tags:
      - app-listings
  /app-listings/{slug}/authorize/:
    post:
      description: Return the provider OAuth authorize URL for connecting an app listing.
      operationId: install
      parameters:
      - in: path
        name: slug
        required: true
        schema:
          maxLength: 255
          minLength: 1
          title: Slug
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AppListingInstallRequestSchema'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppListingInstallResponseSchema'
          description: Successful Response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'
          description: App listing not found
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntityResponse'
          description: Invalid request made to the API.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
          description: Internal server error.
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
          description: Bad gateway error.
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
          description: Service unavailable.
      security:
      - APIKeyHeader: []
      - HTTPBearer: []
      summary: Start an app listing OAuth install
      tags:
      - app-listings
  /app-listings/{slug}/callback/:
    post:
      description: Validate the OAuth callback for the app listing and return a pending-connection id. A sign-in that was started for another app listing is refused.
      operationId: callback
      parameters:
      - in: path
        name: slug
        required: true
        schema:
          maxLength: 255
          minLength: 1
          title: Slug
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AppListingCallbackRequestSchema'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppListingCallbackResponseSchema'
          description: Successful Response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'
          description: App listing not found
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntityResponse'
          description: Invalid request made to the API.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
          description: Internal server error.
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
          description: Bad gateway error.
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
          description: Service unavailable.
      security:
      - APIKeyHeader: []
      - HTTPBearer: []
      summary: Exchange an app listing OAuth callback
      tags:
      - app-listings
  /app-listings/{slug}/check/:
    post:
      description: Confirm a customer's hand-typed workspace/tenant resolves before redirecting to the vendor login. Returns found, not_found, or unreachable.
      operationId: preflight
      parameters:
      - in: path
        name: slug
        required: true
        schema:
          maxLength: 255
          minLength: 1
          title: Slug
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AppListingPreflightRequestSchema'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppListingPreflightResponseSchema'
          description: Successful Response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'
          description: App listing not found
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntityResponse'
          description: Invalid request made to the API.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
          description: Internal server error.
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
          description: Bad gateway error.
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
          description: Service unavailable.
      security:
      - APIKeyHeader: []
      - HTTPBearer: []
      summary: Check a workspace resolves before connecting
      tags:
      - app-listings
  /app-listings/{slug}/connect-inputs/:
    get:
      description: Return the per-customer inputs (tenant address, region, or a choice) the connect modal collects before the OAuth redirect. Empty for one-click listings.
      operationId: list_connect_inputs
      parameters:
      - in: path
        name: slug
        required: true
        schema:
          maxLength: 255
          minLength: 1
          title: Slug
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse_ConnectInputSchema_'
          description: Successful Response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'
          description: App listing not found
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntityResponse'
          description: Invalid request made to the API.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
          description: Internal server error.
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
          description: Bad gateway error.
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
          description: Service unavailable.
      security:
      - APIKeyHeader: []
      - HTTPBearer: []
      summary: List an app listing's connect-time inputs
      tags:
      - app-listings
components:
  schemas:
    AppListingInstallRequestSchema:
      description: Request to begin an app listing OAuth install.
      properties:
        inputs:
          additionalProperties:
            maxLength: 2048
            minLength: 1
            type: string
          description: Connect-time inputs collected before the redirect (tenant address, region, or a choice), keyed by input name. Empty for listings that need no inputs.
          propertyNames:
            maxLength: 255
            minLength: 1
          title: Inputs
          type: object
        integration_id:
          anyOf:
          - format: uuid
            type: string
          - type: 'null'
          description: 'For switch/reconnect only: the existing integration to re-authorize in place. Bound into the OAuth state so the claim mutates only this integration. Omit for new connects.'
          title: Integration Id
        intent:
          anyOf:
          - $ref: '#/components/schemas/SwitchIntent'
          - type: 'null'
          description: 'For switch/reconnect only: ''switch'' (API-key -> one-click) or ''reconnect'' (re-authorize). Must be set together with integration_id.'
      title: AppListingInstallRequestSchema
      type: object
    AppListingPreflightRequestSchema:
      description: Request to check whether a customer's hand-typed workspace resolves before the redirect.
      properties:
        inputs:
          additionalProperties:
            maxLength: 2048
            minLength: 1
            type: string
          description: Connect-time inputs to resolve-check, keyed by input name.
          propertyNames:
            maxLength: 255
            minLength: 1
          title: Inputs
          type: object
      title: AppListingPreflightRequestSchema
      type: object
    UnprocessableEntityIssue:
      properties:
        input:
          anyOf:
          - type: string
          - type: integer
          - type: number
          - type: boolean
          - items: {}
            type: array
          - additionalProperties: true
            type: object
          description: The user's input that caused the error.
          title: Input
        loc:
          description: The location of the error. Always contains 1 or 2 elements. The first element is the type of location (e.g. 'body', 'query', 'path', 'header'). The second element is the name of the field that caused the error. If the error is not related to a specific field, the second element is not present.
          items:
            type: string
          title: Loc
          type: array
        msg:
          description: The message of the error. The error message to show to the user.
          title: Msg
          type: string
        type:
          description: The type of the error. Useful for frontend code to handle different types of errors.
          title: Type
          type: string
      required:
      - loc
      - msg
      - type
      - input
      title: UnprocessableEntityIssue
      type: object
    PreflightStatus:
      description: Outcome of the pre-flight resolve check for a hand-typed tenant workspace.
      enum:
      - found
      - not_found
      - unreachable
      title: PreflightStatus
      type: string
    ConnectInputKind:
      description: The kind of a connect-time input the connect modal renders.
      enum:
      - tenant
      - choice
      - region
      title: ConnectInputKind
      type: string
    UnprocessableEntityResponse:
      properties:
        detail:
          description: The detail of the error. This is the error message to show to the user. You should also use the issues field to show more detailed error messages per field. Use this field for a single liner error message.
          title: Detail
          type: string
        issues:
          description: The issues that caused the error. There can be multiple issues. Each issue is a user-facing error message.
          items:
            $ref: '#/components/schemas/UnprocessableEntityIssue'
          title: Issues
          type: array
      required:
      - detail
      - issues
      title: UnprocessableEntityResponse
      type: object
    NotFoundResponse:
      properties:
        detail:
          description: The detail of why the resource was not found.
          title: Detail
          type: string
      required:
      - detail
      title: NotFoundResponse
      type: object
    ServerErrorResponse:
      properties:
        detail:
          description: The detail of why the server returned an error.
          title: Detail
          type: string
      required:
      - detail
      title: ServerErrorResponse
      type: object
    ConnectInputOptionSchema:
      description: One selectable option of a choice/region connect input.
      properties:
        label:
          title: Label
          type: string
        value:
          title: Value
          type: string
      required:
      - value
      - label
      title: ConnectInputOptionSchema
      type: object
    AppListingInstallResponseSchema:
      description: The provider authorize URL to redirect the user to.
      properties:
        authorize_url:
          title: Authorize Url
          type: string
      required:
      - authorize_url
      title: AppListingInstallResponseSchema
      type: object
    AppListingPreflightResponseSchema:
      description: The pre-flight resolve-check outcome.
      properties:
        status:
          $ref: '#/components/schemas/PreflightStatus'
          description: found (safe to redirect), not_found (keep the customer on the form), or unreachable (the customer may proceed with a soft warning).
      required:
      - status
      title: AppListingPreflightResponseSchema
      type: object
    ForbiddenResponse:
      properties:
        detail:
          description: The detail of why the request is forbidden.
          title: Detail
          type: string
      required:
      - detail
      title: ForbiddenResponse
      type: object
    ConnectInputSchema:
      description: A single connect-time input the connect modal renders.
      properties:
        default:
          anyOf:
          - type: string
          - type: 'null'
          title: Default
        helper:
          title: Helper
          type: string
        kind:
          $ref: '#/components/schemas/ConnectInputKind'
          description: tenant (free text), choice (options), or region (dropdown).
        label:
          title: Label
          type: string
        name:
          title: Name
          type: string
        options:
          anyOf:
          - items:
              $ref: '#/components/schemas/ConnectInputOptionSchema'
            type: array
          - type: 'null'
          title: Options
        placeholder:
          title: Placeholder
          type: string
        required:
          title: Required
          type: boolean
      required:
      - kind
      - name
      - label
      - placeholder
      - helper
      - required
      title: ConnectInputSchema
      type: object
    UnauthorizedResponse:
      properties:
        detail:
          description: The detail of why the request is unauthorized.
          title: Detail
          type: string
      required:
      - detail
      title: UnauthorizedResponse
      type: object
    AppListingClaimOntoExistingResponseSchema:
      description: The integration a switch/reconnect re-authorized in place.
      properties:
        integration_id:
          description: The existing integration, now re-authorized (same id, now one-click).
          format: uuid
          title: Integration Id
          type: string
      required:
      - integration_id
      title: AppListingClaimOntoExistingResponseSchema
      type: object
    AppListingConnectionConfigResponseSchema:
      description: The engine-captured connect-time config for a pending connection.
      properties:
        config:
          additionalProperties:
            maxLength: 2048
            type: string
          description: The tenant/region/login config the engine captured at connect time (e.g. Salesforce `login_url`), for the create wizard to show read-only. Empty for one-click listings.
          title: Config
          type: object
      title: AppListingConnectionConfigResponseSchema
      type: object
    PaginatedResponse_ConnectInputSchema_:
      properties:
        data:
          description: The list of ResponseItems.
          items:
            $ref: '#/components/schemas/ConnectInputSchema'
          title: Data
          type: array
        next_page_cursor:
          anyOf:
          - type: string
          - type: 'null'
          description: The cursor to the next page. If there are no more pages, this is None.
        previous_page_cursor:
          anyOf:
          - type: string
          - type: 'null'
          description: The cursor to the previous page. If there are no previous pages, this is None.
      title: PaginatedResponse[ConnectInputSchema]
      type: object
    SwitchIntent:
      description: 'Why an OAuth grant is being captured against an *existing* integration.


        Set on an installation whose grant re-authorizes a connection in place rather than creating a

        new one. ``None`` on a normal new-connect install.'
      enum:
      - switch
      - reconnect
      title: SwitchIntent
      type: string
    AppListingCallbackRequestSchema:
      description: The OAuth callback parameters posted by the frontend callback page.
      properties:
        code:
          maxLength: 2048
          minLength: 1
          title: Code
          type: string
        params:
          additionalProperties:
            maxLength: 2048
            type: string
          description: Extra provider callback query parameters forwarded by the callback page, used to auto-detect the data center where the vendor returns it (e.g. Zoho `location`).
          propertyNames:
            maxLength: 255
            minLength: 1
          title: Params
          type: object
        state:
          maxLength: 512
          minLength: 1
          title: State
          type: string
      required:
      - code
      - state
      title: AppListingCallbackRequestSchema
      type: object
    AppListingCallbackResponseSchema:
      description: 'A pending-connection id.


        The user finalizes it by calling the create endpoint (``POST /integrations/{type}/``) with this

        ``connection_id``. The OAuth-connect flow shares the regular create/preview endpoints.'
      properties:
        connection_id:
          title: Connection Id
          type: string
      required:
      - connection_id
      title: AppListingCallbackResponseSchema
      type: object
  securitySchemes:
    APIKeyHeader:
      in: header
      name: X-API-Key
      type: apiKey
    HTTPBearer:
      scheme: bearer
      type: http