NovumOS Import Jobs API

The import-jobs API from NovumOS — 5 operation(s) for import-jobs.

GitHub OpenAPI

Operations 6

POST /v1/orgs/{org_id}/import-jobs Create Import Job Endpoint #
GET /v1/orgs/{org_id}/import-jobs List Import Jobs Endpoint #
POST /v1/orgs/{org_id}/import-jobs:upload Create Import Upload Endpoint #
GET /v1/orgs/{org_id}/import-jobs/{job_id} Get Import Job Endpoint #
POST /v1/orgs/{org_id}/import-jobs/{job_id}:cancel Cancel Import Job Endpoint #
POST /v1/orgs/{org_id}/import-jobs:databases List Databases Endpoint #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/novumos-app:novumos-app-import-jobs-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

novumos-app-import-jobs-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: NovumOS Import Jobs API
  description: Block-based kanban where agents are first-class users.
  version: 0.0.0
tags:
- name: import-jobs
paths:
  /v1/orgs/{org_id}/import-jobs:
    post:
      tags:
      - import-jobs
      summary: Create Import Job Endpoint
      description: 'Create + start an import (spec §21.9). Admin/owner-only.


        ``notion_api`` (default): body carries the transient Notion ``token`` (§21.10 —

        body only, never a query string) plus ``database_id`` / ``whole_workspace`` and

        optional ``column_property``; the token is registered in the process-local store

        so the worker can claim it. ``export_file`` (NOV-297): body carries ``file_id``

        of a committed upload (from ``:upload`` → ``:commit``; usable as soon as the

        file is ``status=available``) plus optional ``column_property``. Returns the

        job WITHOUT any token.'
      operationId: create_import_job_endpoint_v1_orgs__org_id__import_jobs_post
      parameters:
      - name: org_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Org Id
      - name: X-Board-Version
        in: header
        required: true
        schema:
          type: string
          default: '2026-06-19'
        description: Required on every `/v1` request. Send `2026-06-19`. The middleware validates *presence*, not the value, so an older pinned date keeps working; `Notion-Version` is accepted as a Notion-SDK compatibility fallback when this header is absent.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateImportJobRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportJobResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - IntegrationToken: []
    get:
      tags:
      - import-jobs
      summary: List Import Jobs Endpoint
      description: List the org's import jobs, newest first (keyset pagination). Admin/owner-only.
      operationId: list_import_jobs_endpoint_v1_orgs__org_id__import_jobs_get
      parameters:
      - name: org_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Org Id
      - name: page_size
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 25
          title: Page Size
      - name: start_cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Start Cursor
      - name: X-Board-Version
        in: header
        required: true
        schema:
          type: string
          default: '2026-06-19'
        description: Required on every `/v1` request. Send `2026-06-19`. The middleware validates *presence*, not the value, so an older pinned date keeps working; `Notion-Version` is accepted as a Notion-SDK compatibility fallback when this header is absent.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse_ImportJobResponse_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - IntegrationToken: []
  /v1/orgs/{org_id}/import-jobs:upload:
    post:
      tags:
      - import-jobs
      summary: Create Import Upload Endpoint
      description: 'Mint a presigned POST for a Notion export ``.zip`` (NOV-297). Admin/owner-only.


        Returns the standard file envelope (``upload_url`` + form fields). Flow:

        ``:upload`` → PUT bytes to S3 → ``POST /v1/files/{id}:commit`` → ``POST

        .../import-jobs`` with ``source=export_file`` + this ``file_id`` (the file is

        usable as soon as ``:commit`` returns ``status=available``). Only

        ``application/zip`` is accepted (415 otherwise).'
      operationId: create_import_upload_endpoint_v1_orgs__org_id__import_jobs_upload_post
      parameters:
      - name: org_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Org Id
      - name: X-Board-Version
        in: header
        required: true
        schema:
          type: string
          default: '2026-06-19'
        description: Required on every `/v1` request. Send `2026-06-19`. The middleware validates *presence*, not the value, so an older pinned date keeps working; `Notion-Version` is accepted as a Notion-SDK compatibility fallback when this header is absent.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateImportUploadRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Create Import Upload Endpoint V1 Orgs  Org Id  Import Jobs Upload Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - IntegrationToken: []
  /v1/orgs/{org_id}/import-jobs/{job_id}:
    get:
      tags:
      - import-jobs
      summary: Get Import Job Endpoint
      description: 'Return one import job''s status/counts/error_log/board_id (the wizard polls this).


        Admin/owner-only. A job in another org is a ``404`` (org-scoping, no leak).'
      operationId: get_import_job_endpoint_v1_orgs__org_id__import_jobs__job_id__get
      parameters:
      - name: org_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Org Id
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Job Id
      - name: X-Board-Version
        in: header
        required: true
        schema:
          type: string
          default: '2026-06-19'
        description: Required on every `/v1` request. Send `2026-06-19`. The middleware validates *presence*, not the value, so an older pinned date keeps working; `Notion-Version` is accepted as a Notion-SDK compatibility fallback when this header is absent.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportJobResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - IntegrationToken: []
  /v1/orgs/{org_id}/import-jobs/{job_id}:cancel:
    post:
      tags:
      - import-jobs
      summary: Cancel Import Job Endpoint
      description: 'Cancel a queued/running import (spec §21.9). Admin/owner-only.


        Terminal job → ``409 conflict``. A queued/running job is landed in ``failed``

        (no ``cancelled`` status) and its transient token dropped so an unclaimed job

        never runs. Cancelling an already-running job is best-effort — the runner does

        not poll for cancellation.'
      operationId: cancel_import_job_endpoint_v1_orgs__org_id__import_jobs__job_id__cancel_post
      parameters:
      - name: org_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Org Id
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Job Id
      - name: X-Board-Version
        in: header
        required: true
        schema:
          type: string
          default: '2026-06-19'
        description: Required on every `/v1` request. Send `2026-06-19`. The middleware validates *presence*, not the value, so an older pinned date keeps working; `Notion-Version` is accepted as a Notion-SDK compatibility fallback when this header is absent.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportJobResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - IntegrationToken: []
  /v1/orgs/{org_id}/import-jobs:databases:
    post:
      tags:
      - import-jobs
      summary: List Databases Endpoint
      description: 'List the Notion databases the token can see, to pick from (spec §21.9/§21.10).


        Admin/owner-only. The transient token is carried in the request body (never a

        URL/query string — proxies log those) and is used once to build the Notion

        source, then dropped; nothing is persisted. Returns ``[{id, title}]``.'
      operationId: list_databases_endpoint_v1_orgs__org_id__import_jobs_databases_post
      parameters:
      - name: org_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Org Id
      - name: X-Board-Version
        in: header
        required: true
        schema:
          type: string
          default: '2026-06-19'
        description: Required on every `/v1` request. Send `2026-06-19`. The middleware validates *presence*, not the value, so an older pinned date keeps working; `Notion-Version` is accepted as a Notion-SDK compatibility fallback when this header is absent.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListDatabasesRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListDatabasesResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - IntegrationToken: []
components:
  schemas:
    PaginatedResponse_ImportJobResponse_:
      properties:
        object:
          type: string
          title: Object
          default: list
        results:
          items:
            $ref: '#/components/schemas/ImportJobResponse'
          type: array
          title: Results
        has_more:
          type: boolean
          title: Has More
          default: false
        next_cursor:
          anyOf:
          - type: string
          - type: 'null'
          title: Next Cursor
        page_size:
          type: integer
          title: Page Size
          default: 25
      type: object
      required:
      - results
      title: PaginatedResponse[ImportJobResponse]
    CreateImportJobRequest:
      properties:
        source:
          type: string
          enum:
          - notion_api
          - export_file
          title: Source
          default: notion_api
        token:
          anyOf:
          - type: string
            minLength: 1
          - type: 'null'
          title: Token
        file_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: File Id
        database_id:
          anyOf:
          - type: string
            minLength: 1
          - type: 'null'
          title: Database Id
        column_property:
          anyOf:
          - type: string
          - type: 'null'
          title: Column Property
        whole_workspace:
          type: boolean
          title: Whole Workspace
          default: false
      type: object
      title: CreateImportJobRequest
      description: "Body for ``POST /v1/orgs/{org_id}/import-jobs`` (spec §21.9 / §21.10).\n\nTwo transports, selected by ``source``:\n\n* **``notion_api``** (default) — ``token`` is the Notion internal-integration\n  token, a transient secret carried ONLY in this request body (never a query\n  string / URL, which proxies log; §21.10). ``file_id`` is forbidden. Two\n  sub-modes: single-DB (``database_id`` names the one database; optional\n  ``column_property`` names the Notion status/select property whose options\n  become columns — blank ⇒ auto-detect) or whole-workspace\n  (``whole_workspace: true`` — walk ALL shared databases → one board each with\n  best-effort inter-DB relation links; ``database_id`` omitted).\n* **``export_file``** (NOV-297) — import a previously-uploaded Notion export\n  ``.zip``. ``file_id`` names the committed File\n  (upload → commit → create; usable as soon as the file is ``status=available``;\n  see the ``:upload`` endpoint). ``token``/``database_id``/``whole_workspace``\n  are forbidden;\n  ``column_property`` is an optional per-database column-driver hint. Always a\n  whole-file import (one board per database in the export).\n\nThese seed the job's ``cursor_state`` exactly as the runner reads it."
    CreateImportUploadRequest:
      properties:
        filename:
          type: string
          maxLength: 255
          minLength: 1
          title: Filename
        content_type:
          type: string
          maxLength: 255
          minLength: 1
          title: Content Type
          default: application/zip
        size_bytes:
          anyOf:
          - type: integer
            minimum: 1.0
          - type: 'null'
          title: Size Bytes
      type: object
      required:
      - filename
      title: CreateImportUploadRequest
      description: 'Body for ``POST /v1/orgs/{org_id}/import-jobs:upload`` (NOV-297, §21.10).


        Mints a presigned POST for the Notion export ``.zip``. ``content_type`` MUST

        be ``application/zip`` (415 otherwise). ``size_bytes`` is an optional presign

        hint; the server caps via the configured upload limit regardless. The client

        PUTs the bytes, calls the existing ``POST /v1/files/{id}:commit``, then creates

        the import job with ``source=export_file`` + this ``file_id`` (importable as

        soon as the file is ``status=available``).'
    ImportJobResponse:
      properties:
        object:
          type: string
          title: Object
          default: import_job
        id:
          type: string
          format: uuid
          title: Id
        org_id:
          type: string
          format: uuid
          title: Org Id
        board_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Board Id
        source:
          type: string
          title: Source
        status:
          type: string
          title: Status
        attempts:
          type: integer
          title: Attempts
        counts:
          additionalProperties: true
          type: object
          title: Counts
        error_log:
          items: {}
          type: array
          title: Error Log
        last_page:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Page
        created_time:
          type: string
          format: date-time
          title: Created Time
        last_edited_time:
          type: string
          format: date-time
          title: Last Edited Time
      type: object
      required:
      - id
      - org_id
      - source
      - status
      - attempts
      - created_time
      - last_edited_time
      title: ImportJobResponse
      description: 'Status object for an ``ImportJob`` (spec §21.9). NEVER carries the token.


        ``counts`` (boards/columns/cards/blocks) drives the wizard''s progress bar and

        ``error_log`` explains a ``partial``/``failed`` run; ``board_id`` is null until

        the worker creates the board and is the deep-link target on success.

        ``last_page`` is the runner''s incremental resume marker

        (``cursor_state.last_page``) surfaced for the live "importing card N…" line —

        the raw ``cursor_state`` (which also holds the target ``database_id`` /

        ``column_property``) is intentionally NOT echoed; only this progress field is.'
    ListDatabasesRequest:
      properties:
        token:
          type: string
          minLength: 1
          title: Token
      type: object
      required:
      - token
      title: ListDatabasesRequest
      description: 'Body for ``POST /v1/orgs/{org_id}/import-jobs:databases`` (spec §21.9/§21.10).


        Token-in-body (not a GET query string) so the transient Notion secret is

        never written to an access log. The token is used once to list the databases

        the integration can see and is then dropped — never stored.'
    NotionDatabaseSummary:
      properties:
        id:
          type: string
          title: Id
        title:
          type: string
          title: Title
      type: object
      required:
      - id
      - title
      title: NotionDatabaseSummary
      description: 'One pickable Notion database: its id + human title (spec §21.9).'
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ListDatabasesResponse:
      properties:
        object:
          type: string
          title: Object
          default: list
        results:
          items:
            $ref: '#/components/schemas/NotionDatabaseSummary'
          type: array
          title: Results
      type: object
      required:
      - results
      title: ListDatabasesResponse
      description: Envelope for the transient-token database listing (spec §21.9).
  securitySchemes:
    IntegrationToken:
      type: http
      scheme: bearer
      description: 'Integration token. Mint one in the app under **Settings → Integrations** and paste the `nov_…` value here. It is sent as `Authorization: Bearer nov_…`, the same credential the API enforces. Browser session cookies are NOT used by try-it-out (the cookie flow additionally requires an `X-CSRF-Token` header this page cannot mint).'