Structify jobs API

openapi: 3.2.0
info:
  contact:
    email: team@structify.ai
    name: Structify Team
  description: Every enterprise's data team.
  license:
    name: Discuss directly with founders for license.
    url: https://structify.ai
  title: Structify account Jobs API
  version: 0.1.0
servers:
- description: Production server
  url: https://api.structify.ai
- description: Local server
  url: http://localhost:8080
security:
- api_key: []
- session_token: []
tags:
- name: jobs
paths:
  /jobs/cancel/{uuid}:
    post:
      operationId: cancel_job
      parameters:
      - description: UUID of the job you want to cancel.
        in: path
        name: uuid
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
          description: Succesfully cancelled a job.
      summary: You successfully cancelled a job.
      tags:
      - jobs
  /jobs/get/{job_id}:
    get:
      operationId: get_job
      parameters:
      - in: path
        name: job_id
        required: true
        schema:
          $ref: '#/components/schemas/JobId'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResponse'
          description: Full job details including info, source entities, and scrapers.
      tags:
      - jobs
  /jobs/list:
    get:
      operationId: jobs_list
      parameters:
      - in: query
        name: offset
        required: false
        schema:
          minimum: 0
          type: integer
      - in: query
        name: limit
        required: false
        schema:
          minimum: 0
          type: integer
      - description: Dataset name to optionally filter jobs by
        in: query
        name: dataset
        required: false
        schema:
          type:
          - string
          - 'null'
      - description: Status to optionally filter jobs by
        in: query
        name: status
        required: false
        schema:
          allOf:
          - $ref: '#/components/schemas/JobStatus'
      - description: List since a specific timestamp
        in: query
        name: since
        required: false
        schema:
          format: date-time
          type:
          - string
          - 'null'
      - description: Type of job to optionally filter jobs by
        in: query
        name: job_type
        required: false
        schema:
          allOf:
          - $ref: '#/components/schemas/JobType'
      - description: seeded kg search term
        in: query
        name: seeded_kg_search_term
        required: false
        schema:
          type:
          - string
          - 'null'
      - description: Node ID to optionally filter jobs by
        in: query
        name: node_id
        required: false
        schema:
          allOf:
          - $ref: '#/components/schemas/WorkflowSessionNodeId'
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/ListJobsResponse'
                type: array
          description: A list of all execution histories
      summary: List all the executions
      tags:
      - jobs
  /jobs/schedule:
    post:
      description: 'One example use case is every single day check the news websites and

        pull them into my dataset.'
      operationId: schedule_job
      responses:
        '200':
          description: Succesfully scheduled a job.
      summary: You successfully scheduled a job.
      tags:
      - jobs
  /jobs/{job_id}/events:
    get:
      operationId: get_job_events
      parameters:
      - description: Id of the job whose events to get.
        in: path
        name: job_id
        required: true
        schema:
          $ref: '#/components/schemas/JobId'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetJobEventsResponse'
          description: Successfully got job events.
        '400':
          description: Job not found
        '401':
          description: Unauthorized
      security:
      - api_key: []
      - session_token: []
      tags:
      - jobs
components:
  schemas:
    Source:
      properties:
        created_at:
          format: date-time
          type: string
        id:
          $ref: '#/components/schemas/SourceId'
        is_summary:
          type: boolean
        link:
          allOf:
          - $ref: '#/components/schemas/SourceLink'
        location:
          allOf:
          - $ref: '#/components/schemas/SourceLocation'
        scraper_id:
          allOf:
          - $ref: '#/components/schemas/ScraperId'
        user_specified:
          type: boolean
      required:
      - id
      - user_specified
      - is_summary
      - created_at
      type: object
    DecodingParams:
      properties:
        parameters:
          items:
            $ref: '#/components/schemas/DecodingParamEnum'
          type: array
      required:
      - parameters
      type: object
    ToolResult:
      oneOf:
      - enum:
        - Pending
        type: string
      - enum:
        - NoResult
        type: string
      - properties:
          Error:
            type: string
        required:
        - Error
        type: object
      - properties:
          Text:
            type: string
        required:
        - Text
        type: object
      - properties:
          CodeExecution:
            $ref: '#/components/schemas/CodeExecutionResult'
        required:
        - CodeExecution
        type: object
      - properties:
          WebMarkdown:
            type: string
        required:
        - WebMarkdown
        type: object
      - properties:
          WebSearch:
            items:
              $ref: '#/components/schemas/DocSnippet'
            type: array
        required:
        - WebSearch
        type: object
      - properties:
          ConnectorSearch:
            items:
              $ref: '#/components/schemas/ConnectorTableResult'
            type: array
        required:
        - ConnectorSearch
        type: object
      - properties:
          NodeLogs:
            items:
              type: string
            type: array
        required:
        - NodeLogs
        type: object
      - enum:
        - Completed
        type: string
      - properties:
          Image:
            $ref: '#/components/schemas/ImageResult'
        required:
        - Image
        type: object
      - properties:
          Pinned:
            type: string
        required:
        - Pinned
        type: object
    Verbosity:
      enum:
      - low
      - medium
      - high
      type: string
    SourceEntity:
      properties:
        created_at:
          format: date-time
          type: string
        id:
          $ref: '#/components/schemas/SourceEntityId'
        job_id:
          allOf:
          - $ref: '#/components/schemas/JobId'
        kg_entity_id:
          allOf:
          - $ref: '#/components/schemas/EntityId'
        label:
          type: string
        llm_id:
          format: int32
          type: integer
        properties:
          additionalProperties:
            $ref: '#/components/schemas/ComplexPropValue'
          type: object
        source_id:
          $ref: '#/components/schemas/SourceId'
      required:
      - id
      - label
      - llm_id
      - created_at
      - properties
      - source_id
      type: object
    ConnectorTableResult:
      properties:
        columns:
          items:
            $ref: '#/components/schemas/ConnectorColumnResult'
          type: array
        database:
          type: string
        description:
          type:
          - string
          - 'null'
        notes:
          type:
          - string
          - 'null'
        schema:
          type: string
        table_name:
          type: string
      required:
      - schema
      - database
      - table_name
      - columns
      type: object
    SaveMemoryInput:
      properties:
        key:
          type: string
        value:
          type: string
      required:
      - key
      - value
      type: object
    ExitInput:
      properties:
        reason:
          type: string
      required:
      - reason
      type: object
    DeleteFileInput:
      properties:
        file:
          type: string
      required:
      - file
      type: object
    InspectStepInput:
      properties:
        step_name:
          type: string
      required:
      - step_name
      type: object
    ScrapePageInput:
      properties:
        batch_scrape:
          type: boolean
        url_property_name:
          type: string
        use_markdown:
          type: boolean
      required:
      - url_property_name
      - batch_scrape
      - use_markdown
      type: object
    ExplorationPhaseId:
      description: 'Identifies the phase of connector exploration


        This enum is used to track which phase of exploration a chat session belongs to.

        It''s stored as JSONB in the database to allow for flexible phase identification.'
      discriminator:
        propertyName: type
      oneOf:
      - description: 'First phase: discovering all databases in the connector'
        properties:
          connector_id:
            $ref: '#/components/schemas/ConnectorId'
          type:
            enum:
            - discover_databases
            type: string
        required:
        - connector_id
        - type
        type: object
      - description: 'Second phase: discovering all schemas in a database'
        properties:
          database_id:
            $ref: '#/components/schemas/ConnectorDatabaseId'
          database_name:
            type: string
          type:
            enum:
            - discover_schemas
            type: string
        required:
        - database_id
        - database_name
        - type
        type: object
      - description: 'Third phase: discovering all tables in a schema'
        properties:
          schema_id:
            $ref: '#/components/schemas/ConnectorSchemaId'
          schema_name:
            type: string
          type:
            enum:
            - discover_tables
            type: string
        required:
        - schema_id
        - schema_name
        - type
        type: object
      - description: 'Fourth phase: discovering columns for a specific table'
        properties:
          table_id:
            $ref: '#/components/schemas/ConnectorTableId'
          table_name:
            type: string
          type:
            enum:
            - discover_columns
            type: string
        required:
        - table_id
        - table_name
        - type
        type: object
      - description: 'Initial phase: discovering all API resources'
        properties:
          connector_id:
            $ref: '#/components/schemas/ConnectorId'
          type:
            enum:
            - discover_api_resources
            type: string
        required:
        - connector_id
        - type
        type: object
      - description: 'Second phase: discovering fields for a specific API resource'
        properties:
          resource_name:
            type: string
          table_id:
            $ref: '#/components/schemas/ConnectorTableId'
          type:
            enum:
            - discover_api_fields
            type: string
        required:
        - table_id
        - resource_name
        - type
        type: object
    RequiredEntity:
      additionalProperties: false
      properties:
        entity_id:
          allOf:
          - $ref: '#/components/schemas/EntityId'
        seeded_entity_id:
          description: The integer id corresponding to an entity in the seeded entity graph (different from the global dataset entity id)
          minimum: 0
          type: integer
      required:
      - seeded_entity_id
      type: object
    TimeStampedJobEvent:
      properties:
        body:
          $ref: '#/components/schemas/JobEventBody'
        created_at:
          format: date-time
          type: string
      required:
      - created_at
      - body
      type: object
    RequiredProperty:
      additionalProperties: false
      properties:
        property_names:
          description: If there are multiple properties, it can match just one of them
          items:
            type: string
          type: array
        table_name:
          description: The table name of the entity to update
          type: string
      required:
      - table_name
      - property_names
      type: object
    SaveRequirement:
      description: It's an OR statement across these.
      oneOf:
      - $ref: '#/components/schemas/RequiredRelationship'
      - $ref: '#/components/schemas/RequiredEntity'
      - $ref: '#/components/schemas/RequiredProperty'
    ApiExecuteInput:
      properties:
        code:
          type: string
      required:
      - code
      type: object
    Input:
      oneOf:
      - properties:
          PDF:
            $ref: '#/components/schemas/PDFIngestor'
        required:
        - PDF
        type: object
      - properties:
          Web:
            $ref: '#/components/schemas/WebSearch'
        required:
        - Web
        type: object
    MembershipId:
      format: uuid
      type: string
    SaveApiResourceInput:
      properties:
        description:
          type:
          - string
          - 'null'
        endpoint:
          type: string
        name:
          type: string
        notes:
          type:
          - string
          - 'null'
      required:
      - name
      - endpoint
      type: object
    SaveSchemaInput:
      properties:
        description:
          type:
          - string
          - 'null'
        name:
          type: string
        notes:
          type:
          - string
          - 'null'
      required:
      - name
      type: object
    BasicPropValue:
      oneOf:
      - type: string
      - format: int64
        type: integer
      - type: boolean
      - format: double
        type: number
    ImageMeta:
      properties:
        document_name:
          type:
          - string
          - 'null'
        document_page:
          format: int32
          minimum: 0
          type:
          - integer
          - 'null'
        image:
          type:
          - string
          - 'null'
        ocr_content:
          type:
          - string
          - 'null'
      required:
      - image
      type: object
    ViewPageInput:
      properties:
        page_number:
          format: int32
          minimum: 0
          type: integer
      required:
      - page_number
      type: object
    SourceLocation:
      oneOf:
      - properties:
          Text:
            properties:
              byte_offset:
                minimum: 0
                type: integer
            required:
            - byte_offset
            type: object
        required:
        - Text
        type: object
      - properties:
          Visual:
            properties:
              x:
                minimum: 0
                type: integer
              y:
                minimum: 0
                type: integer
            required:
            - x
            - y
            type: object
        required:
        - Visual
        type: object
      - properties:
          Page:
            properties:
              page_number:
                format: int32
                minimum: 0
                type: integer
            required:
            - page_number
            type: object
        required:
        - Page
        type: object
    InternalErrorKind:
      description: 'Categorizes the kind of internal error that occurred during LLM generation.

        This allows the frontend to render appropriate error messages without regex matching.'
      enum:
      - unknown
      - context_limit
      - rate_limited
      - timeout
      - connection_error
      type: string
    NodeSummary:
      properties:
        data_preview:
          type:
          - string
          - 'null'
        image:
          format: binary
          type:
          - string
          - 'null'
        in_dashboard:
          type: boolean
        name:
          type: string
      required:
      - name
      - in_dashboard
      type: object
    RequestClarificationInput:
      properties:
        column_name:
          type:
          - string
          - 'null'
        question:
          type: string
        table_name:
          type: string
      required:
      - table_name
      - question
      type: object
    MergeStrategy:
      oneOf:
      - description: 'Property with unique 1:1 correspondence to its parent.


          Merge based on this property 100% of the time'
        enum:
        - Unique
        type: string
      - properties:
          Probabilistic:
            $ref: '#/components/schemas/MergeConfig'
        required:
        - Probabilistic
        type: object
      - enum:
        - NoSignal
        type: string
    FormatterMeta:
      oneOf:
      - properties:
          ImageMeta:
            $ref: '#/components/schemas/ImageMeta'
        required:
        - ImageMeta
        type: object
      - properties:
          WebMeta:
            $ref: '#/components/schemas/WebMeta'
        required:
        - WebMeta
        type: object
      - properties:
          TextMeta:
            $ref: '#/components/schemas/TextMeta'
        required:
        - TextMeta
        type: object
      - properties:
          ScraperMeta:
            $ref: '#/components/schemas/ScraperMeta'
        required:
        - ScraperMeta
        type: object
    ConnectorId:
      format: uuid
      type: string
    AddDependencyInput:
      properties:
        package_name:
          type: string
        version_spec:
          type:
          - string
          - 'null'
      required:
      - package_name
      type: object
    PartialDate:
      oneOf:
      - properties:
          day:
            type:
            - integer
            - 'null'
          month:
            type:
            - integer
            - 'null'
          original_string:
            type: string
          year:
            type: integer
        required:
        - year
        - original_string
        title: PartialDateObject
        type: object
      - description: 'Date string in formats: ''YYYY'', ''YYYY-MM'', ''YYYY-MM-DD'', ''DD-MM-YYYY'', ''MM-DD-YYYY'', ''Jan 3, 2023'', ''3 Jan 2023'', ''2023 Apr 3'', etc.'
        title: PartialDateString
        type: string
      title: PartialDateProperty
    SourceId:
      format: uuid
      type: string
    SpeakerTag:
      enum:
      - user
      - system
      - assistant
      type: string
    ChatEvent:
      description: Events in a chat session timeline, including messages and unified tool calls/results
      oneOf:
      - properties:
          TextMessage:
            properties:
              message:
                type: string
            required:
            - message
            type: object
        required:
        - TextMessage
        type: object
      - properties:
          Thinking:
            properties:
              block_id:
                format: int64
                minimum: 0
                type: integer
              complete:
                type: boolean
              content:
                type: string
            required:
            - content
            - complete
            - block_id
            type: object
        required:
        - Thinking
        type: object
      - properties:
          File:
            description: 'The file event can''t be serialized to the database safely without the content.

              When streaming, we start with the path only, then add the content as we go.'
            properties:
              block_id:
                format: int64
                minimum: 0
                type: integer
              complete:
                type: boolean
              content:
                type:
                - string
                - 'null'
              path:
                type: string
            required:
            - path
            - complete
            - block_id
            type: object
        required:
        - File
        type: object
      - properties:
          Action:
            properties:
              actions:
                items:
                  $ref: '#/components/schemas/ActionDef'
                type: array
              block_id:
                format: int64
                minimum: 0
                type: integer
              complete:
                type: boolean
            required:
            - actions
            - complete
            - block_id
            type: object
        required:
        - Action
        type: object
      - properties:
          Connector:
            properties:
              description:
                type:
                - string
                - 'null'
              env_vars:
                items:
                  type: string
                type: array
              name:
                type: string
            required:
            - name
            - env_vars
            type: object
        required:
        - Connector
        type: object
      - properties:
          ToolCall:
            properties:
              block_id:
                format: int64
                minimum: 0
                type: integer
              complete:
                type: boolean
              invocation:
                $ref: '#/components/schemas/ToolInvocation'
              tool_result:
                $ref: '#/components/schemas/ToolResult'
            required:
            - invocation
            - tool_result
            - block_id
            - complete
            type: object
        required:
        - ToolCall
        type: object
      - properties:
          Question:
            properties:
              block_id:
                format: int64
                minimum: 0
                type: integer
              complete:
                type: boolean
              content:
                type: string
              options:
                items:
                  type: string
                type: array
            required:
            - content
            - complete
            - options
            - block_id
            type: object
        required:
        - Question
        type: object
      - properties:
          InternalError:
            properties:
              error_kind:
                $ref: '#/components/schemas/InternalErrorKind'
              message:
                type: string
            required:
            - message
            type: object
        required:
        - InternalError
        type: object
      - properties:
          ReviewRequest:
            properties:
              node_summaries:
                items:
                  $ref: '#/components/schemas/NodeSummary'
                type: array
            required:
            - node_summaries
            type: object
        required:
        - ReviewRequest
        type: object
      - properties:
          AttachedFile:
            properties:
              image_bytes:
                format: binary
                type:
                - string
                - 'null'
              path:
                type: string
            required:
            - path
            type: object
        required:
        - AttachedFile
        type: object
      - properties:
          ConnectorRequest:
            properties:
              connector_id:
                $ref: '#/components/schemas/ConnectorId'
            required:
            - connector_id
            type: object
        required:
        - ConnectorRequest
        type: object
      - properties:
          UserInterrupted:
            type: object
        required:
        - UserInterrupted
        type: object
      - properties:
          IssueFound:
            properties:
              admin_override:
                type: boolean
              description:
                type: string
              title:
                type: string
            required:
            - title
            - description
            - admin_override
            type: object
        required:
        - IssueFound
        type: object
    JobStatus:
      enum:
      - Queued
      - Running
      - Completed
      - Failed
      type: string
    LLMRelationship:
      additionalProperties: false
      properties:
        properties:
          additionalProperties:
            $ref: '#/components/schemas/BasicPropValue'
          type: object
        source:
          minimum: 0
          type: integer
        target:
          minimum: 0
          type: integer
        type:
          type: string
      required:
      - type
      - source
      - target
      type: object
    PDFIngestor:
      additionalProperties: false
      description: Ingest all pages of a PDF and process them independently.
      properties:
        page:
          format: int32
          minimum: 0
          type:
          - integer
          - 'null'
        path:
          type: string
      required:
      - path
      type: object
    GetJobEventsResponse:
      properties:
        events:
          items:
            $ref: '#/components/schemas/TimeStampedJobEvent'
          type: array
      required:
      - events
      type: object
    LLMEntity:
      additionalProperties: false
      properties:
        id:
          minimum: 0
          type: integer
        properties:
          additionalProperties:
            $ref: '#/components/schemas/BasicPropValue'
          type: object
        type:
          type: string
      required:
      - id
      - type
      - properties
      type: object
    CreateConnectorInput:
      properties:
        connector_type:
          type: string
        description:
          type:
          - string
          - 'null'
        name:
          type: string
        secrets:
          items:
            type: string
          type: array
      required:
      - name
      - connector_type
      type: object
    ReadNodeLogsInput:
      properties:
        log_type:
          type:
          - string
          - 'null'
        node_function_name:
          type: string
      required:
      - node_function_name
      type: object
    ConnectorTableId:
      format: uuid
      type: string
    TextMeta:
      properties:
        text:
          type: string
      required:
      - text
      type: object
    Url:
      oneOf:
      - description: Url string
        title: UrlString
        type: string
      - properties:
          original_string:
            type: string
          url:
            type: string
        required:
        - url
        - original_string
        title: UrlObject
        type: object
      title: UrlProperty
    RunBashInput:
      properties:
        command:
          type: string
        connector:
          type:
          - string
          - 'null'
        working_dir:
          type:
          - string
          - 'null'
      required:
      - command
      type: object
    CodeExecutionResult:
      properties:
        return_code:
          format: int32
          type: integer
        stderr:
          type: string
        stdout:
          type: string
      required:
      - stdout
      - stderr
      - return_code
      type: object
    ConnectorExplorationInput:
      properties:
        connector_id:
          $ref: '#/components/schemas/ConnectorId'
        exploration_phase_id:
          $ref: '#/components/schemas/ExplorationPhaseId'
        exploration_run_id:
          $ref: '#/components/schemas/ExplorationRunId'
        strategy:
          $ref: '#/components/schemas/ExplorationStrategy'
      required:
      - connector_id
      - exploration_phase_id
      - exploration_run_id
      - strategy
      type: object
    SaveInput:
      properties:
        knowledge_graph:
          $ref: '#/components/schemas/LLMKnowledgeGraph'
        reason:
          type: string
        sources:
          items:
            type: string
          type: array
      required:
      - knowledge_graph
      - sources
      - reason
      type: object
    PropertyDescriptor:
      additionalProperties: false
      properties:
        description:
          type: string
        merge_strategy:
          $ref: '#/components/schemas/MergeStrategy'
        name:
          type: string
        prop_type:
          $ref: '#/components/schemas/PropertyType'
      required:
      - name
      - description
      type: object
    SaveColumnInput:
      properties:
        column_name:
          type: string
        column_type:
          type: string
        notes:
          type:
          - string
          - 'null'
      required:
      - column_name
      - column_type
      type: object
    JobType:
      enum:
      - Web
      - Pdf
      - Derive
      - Scrape
      - Match
      - ConnectorExplore
      - DatahubIngestion
      type: string
    ExplorationRunId:
      format: uuid
      type: string
    ScraperMeta:
      properties:
        html_content:
          type: string
        url:
          type: string
      required:
      - html_content
      - url
      type: object
    RequiredRelationship:
      additionalProperties: false
      properties:
        relationship_name:
          type: string
      required:
      - relationship_name
      type: object
    WorkflowSessionNodeId:
      format: uuid
      type: string
    LLMKnowledgeGraph:
      additionalProperties: false
      description: 'Knowledge graph info structured to deserialize and display

        in the same format that the LLM outputs.

        Also the first representation of an LLM output in the pipeline from raw tool output to being merged into a DB'
      properties:
        entities:
          items:
            $ref: '#/components/schemas/LLMEntity'
          type: array
        relationships:
          items:
            $ref: '#/components/schemas/LLMRelationship'
          type: array
      required:
      - entities
      type: object
    NavigationType:
      enum:
      - visual
      - text
      type: string
    InputType:
      oneOf:
      - properties:
          Agent:
            $ref: '#/components/schemas/Input'
        required:
        - Agent
        type: object
      - properties:
          TransformationPrompt:
            type: string
        required:
        - TransformationPrompt
        type: object
      - properties:
          ScrapeFromUrlProperty:
            $ref: '#/components/schemas/ScrapePageInput'
        required:
        - ScrapeFromUrlProperty
        type: object
      - properties:
          ScrapeUrl:
            $ref: '#/components/schemas/ScrapePageUrlInput'
        required:
        - ScrapeUrl
        type: object
      - properties:
          DatahubIngestion:
            $ref: '#/components/schemas/DatahubIngestionInput'
        required:
        - DatahubIngestion
        type: object
      - properties:
          ConnectorExploration:
            $ref: '#/components/schemas/ConnectorExplorationInput'
        required:
        - ConnectorExploration
        type: object
    Job:
      properties:
        created_at:
          format: date-time
          type: string
        dataset_id:
          allOf:
          - $ref: '#/components/schemas/DatasetId'
        exploration_run_id:
          allOf:
          - $ref: '#/components/schemas/ExplorationRunId'
        id:
          $ref: '#/components/schemas/JobId'
        job_type:
          $ref: '#/components/schemas/JobType'
        max_errors:
          format: int32
          type:
          - integer
          - 'null'
        max_execution_time_secs:
          format: int32
          type:
          - integer
          - 'null'
        max_steps_without_save:
          format: int32
          type: integer
        max_total_steps:
          format: int32
          type:
          - integer
          - 'null'
        membership_id:
          $ref: '#/components/schemas/MembershipId'
        message:
          description: A message about the status of the job at completion
          type:
          - string
          - 'null'
        node_id:
          allOf:
          - $ref: '#/components/schemas/WorkflowSessionNodeId'
        p

# --- truncated at 32 KB (73 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/structify/refs/heads/main/openapi/structify-jobs-api-openapi.yml