Oneprofile Find Subdomains 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 Find Subdomains API
  version: 1.0.42765316646
tags:
- description: Endpoints for discovering a domain's subdomains from public certificate logs and landing the results in a table.
  name: find-subdomains
paths:
  /subdomain-searches/:
    post:
      description: Begin reading the public record of subdomains for a domain. Returns immediately with a pending search; poll the search endpoint until it reaches a terminal status. It usually answers in seconds, but a domain the fast index does not cover falls back to reading raw certificate logs, which is slow and frequently has to be retried. That is why this does not answer inline.
      operationId: start_subdomain_search
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartSubdomainSearchRequestSchema'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubdomainSearchResponseSchema'
          description: Successful Response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequiredResponse'
          description: Not enough credits, or the plan does not include subdomain search.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenResponse'
          description: Forbidden
        '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 a subdomain search
      tags:
      - find-subdomains
  /subdomain-searches/{search_id}/:
    get:
      description: Poll a search until its status is succeeded or failed. A failed search carries an error code and whether another attempt is worth making. With this upstream source, it usually is.
      operationId: get_subdomain_search
      parameters:
      - in: path
        name: search_id
        required: true
        schema:
          format: uuid
          title: Search Id
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubdomainSearchResponseSchema'
          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: No such subdomain search.
        '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 subdomain search
      tags:
      - find-subdomains
  /subdomain-searches/{search_id}/import/:
    post:
      description: Land a finished search's hostnames into a new table, one row per hostname. Separate from the search itself so results can be reviewed before a table is committed.
      operationId: create_table_from_subdomain_search
      parameters:
      - in: path
        name: search_id
        required: true
        schema:
          format: uuid
          title: Search Id
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTableFromSubdomainSearchRequestSchema'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateTableFromSubdomainSearchResponseSchema'
          description: Successful Response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequiredResponse'
          description: Not enough credits, or the plan does not allow a table this size.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'
          description: No such subdomain search or folder.
        '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: Create a table from a subdomain search
      tags:
      - find-subdomains
  /tables/{table_id}/subdomain-feed/:
    get:
      description: 'A table made from a subdomain search reads its domain again to add the subdomains it did not have: when somebody refreshes it, and on the table''s refresh schedule (`/tables/{table_id}/schedule/`). This says which domain, when it was last read, what the newest read added, and whether one is under way. Only a table whose read says `has_subdomain_feed` has one; every other table answers 404.'
      operationId: get_subdomain_feed
      parameters:
      - in: path
        name: table_id
        required: true
        schema:
          format: uuid
          title: Table Id
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubdomainFeedSchema'
          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: No subdomain search made this table.
        '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 table's subdomain feed
      tags:
      - find-subdomains
  /tables/{table_id}/subdomain-feed/sync/:
    post:
      description: Read the table's domain again and add, as new rows, the subdomains the table never had. Rows somebody deleted stay deleted. Returns at once with the feed checking; read the feed until `checking` is false. Reading costs nothing; the table's enrichment columns run over the rows it adds, as they do for any new row.
      operationId: refresh_subdomain_feed
      parameters:
      - in: path
        name: table_id
        required: true
        schema:
          format: uuid
          title: Table Id
          type: string
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubdomainFeedSchema'
          description: Successful Response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequiredResponse'
          description: Not enough credits, or the plan does not include subdomain search.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'
          description: No subdomain search made this table, or the table is in Trash.
        '409':
          description: A check for this table is already under way.
        '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 subdomain table for new subdomains now
      tags:
      - find-subdomains
components:
  schemas:
    ForbiddenResponse:
      properties:
        detail:
          description: The detail of why the request is forbidden.
          title: Detail
          type: string
      required:
      - detail
      title: ForbiddenResponse
      type: object
    SubdomainFeedRefreshSchema:
      description: One read a table made of its domain, to add the subdomains it did not have.
      properties:
        created_at:
          description: When the read started.
          format: date-time
          title: Created At
          type: string
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
        error_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Error Code
        id:
          format: uuid
          title: Id
          type: string
        new_hostnames:
          description: Hostnames this read found that the table never had a row for. Larger than rows_created when the plan's rows per table left no room for some; a later check offers those again once there is room.
          title: New Hostnames
          type: integer
        retryable:
          description: Whether trying again could plausibly work.
          title: Retryable
          type: boolean
        rows_created:
          description: Rows this read added to the table.
          title: Rows Created
          type: integer
        status:
          $ref: '#/components/schemas/SubdomainSearchStatus'
          description: Succeeded once its new rows are in the table. Pending or running while `checking` is false means it stopped answering and added nothing.
        trigger:
          $ref: '#/components/schemas/SubdomainSearchTrigger'
          description: 'Who asked: refresh is a person, schedule is the table''s refresh schedule.'
        updated_at:
          description: 'When the read last changed: when it ended, once ended.'
          format: date-time
          title: Updated At
          type: string
      required:
      - id
      - trigger
      - status
      - new_hostnames
      - rows_created
      - error
      - error_code
      - retryable
      - created_at
      - updated_at
      title: SubdomainFeedRefreshSchema
      type: object
    UnauthorizedResponse:
      properties:
        detail:
          description: The detail of why the request is unauthorized.
          title: Detail
          type: string
      required:
      - detail
      title: UnauthorizedResponse
      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
    CreateTableFromSubdomainSearchResponseSchema:
      description: The table a search was turned into.
      properties:
        hostnames_found:
          description: What the search found, before any cap. Larger than rows_created when the per-search cap trimmed what was stored or the organisation's per-table row limit clamped the landing.
          title: Hostnames Found
          type: integer
        rows_created:
          title: Rows Created
          type: integer
        table_id:
          format: uuid
          title: Table Id
          type: string
        table_name:
          title: Table Name
          type: string
      required:
      - table_id
      - table_name
      - rows_created
      - hostnames_found
      title: CreateTableFromSubdomainSearchResponseSchema
      type: object
    SubdomainSearchStatus:
      description: Where one subdomain search has got to.
      enum:
      - pending
      - running
      - succeeded
      - failed
      title: SubdomainSearchStatus
      type: string
    ServerErrorResponse:
      properties:
        detail:
          description: The detail of why the server returned an error.
          title: Detail
          type: string
      required:
      - detail
      title: ServerErrorResponse
      type: object
    SubdomainFeedSchema:
      description: A table made from a subdomain search, which reads its domain again to add new subdomains.
      properties:
        checking:
          description: 'Whether a check for new subdomains is under way now: from the moment it starts until its new rows are in the table.'
          title: Checking
          type: boolean
        domain:
          description: The domain the table reads.
          title: Domain
          type: string
        last_read_at:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          description: 'When the newest successful read started: a refresh, or the search the table was made from.'
          title: Last Read At
        last_refresh:
          anyOf:
          - $ref: '#/components/schemas/SubdomainFeedRefreshSchema'
          - type: 'null'
          description: The newest read the table made, in any state; null until it refreshes once.
        table_id:
          format: uuid
          title: Table Id
          type: string
      required:
      - table_id
      - domain
      - last_refresh
      - last_read_at
      - checking
      title: SubdomainFeedSchema
      type: object
    CreateTableFromSubdomainSearchRequestSchema:
      description: Turn a finished search into a table.
      properties:
        folder_id:
          anyOf:
          - format: uuid
            type: string
          - type: 'null'
          description: The folder to make the table in, as when the search is started from inside one on the Tables list. Leave it out for the top level.
          title: Folder Id
        table_name:
          maxLength: 255
          minLength: 1
          title: Table Name
          type: string
      required:
      - table_name
      title: CreateTableFromSubdomainSearchRequestSchema
      type: object
    PaymentRequiredResponse:
      properties:
        detail:
          description: The detail of why payment is required.
          title: Detail
          type: string
      required:
      - detail
      title: PaymentRequiredResponse
      type: object
    SubdomainSearchTrigger:
      description: 'Why a search ran: somebody searched, or a table it fills read its domain again.


        A table made from a search is a feed: every later read of the same domain

        is a search of its own, attached to the table from the start, and lands

        only the hostnames the table has never had a row for.'
      enum:
      - search
      - refresh
      - schedule
      title: SubdomainSearchTrigger
      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
    StartSubdomainSearchRequestSchema:
      description: Start a search for one domain's subdomains.
      properties:
        domain:
          description: The domain to search, e.g. slack.com. A pasted URL is trimmed.
          maxLength: 512
          minLength: 1
          title: Domain
          type: string
      required:
      - domain
      title: StartSubdomainSearchRequestSchema
      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
    SubdomainSearchResponseSchema:
      description: One search and whatever it has found so far.
      properties:
        created_at:
          format: date-time
          title: Created At
          type: string
        domain:
          title: Domain
          type: string
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
        error_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Error Code
        hostnames:
          description: 'Discovered hostnames, newest first sighting first. Empty until the search succeeds. At most the per-search cap (5,000 by default): a larger domain is trimmed to its newest names and partial is true.'
          items:
            type: string
          title: Hostnames
          type: array
        hostnames_found:
          description: How many distinct hostnames the search found, before the per-search cap. Larger than len(hostnames) when the cap trimmed the list; use this for the headline count.
          title: Hostnames Found
          type: integer
        id:
          format: uuid
          title: Id
          type: string
        partial:
          description: True when hostnames is a slice of what was found, which is when hostnames_found exceeds len(hostnames). The names kept are the newest first sightings.
          title: Partial
          type: boolean
        retryable:
          description: Whether running the same search again could plausibly work.
          title: Retryable
          type: boolean
        rows_created:
          title: Rows Created
          type: integer
        rows_to_add:
          description: 'How many rows turning this search into a table would add: the hostnames stored, cut to the plan''s rows per table. Put it on the create button; 0 until the search succeeds.'
          title: Rows To Add
          type: integer
        status:
          $ref: '#/components/schemas/SubdomainSearchStatus'
        table_id:
          anyOf:
          - format: uuid
            type: string
          - type: 'null'
          title: Table Id
      required:
      - id
      - domain
      - status
      - hostnames
      - hostnames_found
      - partial
      - rows_to_add
      - table_id
      - rows_created
      - error
      - error_code
      - retryable
      - created_at
      title: SubdomainSearchResponseSchema
      type: object
  securitySchemes:
    APIKeyHeader:
      in: header
      name: X-API-Key
      type: apiKey
    HTTPBearer:
      scheme: bearer
      type: http