NovumOS Import Jobs API
The import-jobs API from NovumOS — 5 operation(s) for import-jobs.
The import-jobs API from NovumOS — 5 operation(s) for import-jobs.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
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.curl "https://apis.io/api/v1/apis/novumos-app:novumos-app-import-jobs-api"
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.
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: 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).'