Import and async tasks
Use the import API to create individuals of many classes in one request and to join them by their source-system keys. A real import is queued and returns a task ID. You poll the task to get the outcome. Large relationship loads work the same way. For more information, see Importing individuals.
This section contains the following API calls:
- Import individuals
- Get an async task
- Undo an import
- Add relationships in bulk
- Get a bulk relationship task
Before you start
Every call needs an Authorization: Bearer <token> header and the nsfilter query parameter.
- Individuals land in the ontology's live version. Until you promote the first version, a queued import, an undo, and a bulk relationship load return
409. - Every class you import into needs a live collection mapping with a collection. For more information, see Individuals.
- On the
/ontologies/{ontologyId}/importroutes,nsfiltermust name only namespaces the ontology belongs to. Otherwise the call returns404. - You can't cancel or delete an async task.
One ID links the calls on this page. The _taskId that an import returns is the ID you poll with Get an async task and the ID you pass to Undo an import. The service also stamps it on every individual the import creates, at properties._provenance.asyncTaskId.
For the full permission model, see Permissions.
Import individuals
Creates or updates individuals across several classes, and sets relationships between them. The body is a flat JSON array of individuals. Options are query parameters.
By default the import is queued and returns 202 with a task ID. A 202 means the service stored the request and will run it, not that the data conforms. To check the result, poll Get an async task and read _response._body._conforms.
To validate without writing, set dryRun=true. A dry run answers inline with 200 if the data conforms or 422 if it doesn't. Only a dry run returns the per-element plan, which shows what each element would do and why a conflict occurred.
You need INDIVIDUALS_CREATE on every _classId, and INDIVIDUALS_EDIT on every class whose elements carry import-form relationships.
Endpoints
POST /aosvc/api/v1/ontologies/{ontologyId}/import
Parameters
Path
| Parameter | Type | Description | Required |
|---|---|---|---|
ontologyId | String | The ID of the application ontology. | Required |
Query
| Parameter | Type | Description | Required |
|---|---|---|---|
nsfilter | String | The namespace filter. Must name only namespaces the ontology belongs to. | Required |
dryRun | Boolean | Set to true to validate and answer inline without writing or queuing anything. | Optional, default is false |
mode | String | UPSERT matches existing individuals on their external key and updates them. CREATE_ONLY always creates. | Optional, default is UPSERT |
rollback | Boolean | Set to false to keep what a failed import created. When true, a failed import deletes the individuals it created. | Optional, default is true |
facets | String | ENFORCE rejects value-facet failures, such as datatype and range checks. REPORT turns them into warnings. Count checks stay enforced. | Optional, default is ENFORCE |
modelRevision | Integer | The ontology revision to validate against. | Optional, default is the current revision |
Body
A non-empty JSON array of individuals, up to 10 MB. Order doesn't matter. The service groups elements by class.
| Parameter | Type | Description | Required |
|---|---|---|---|
_classId | String | The ID of the individual's class. | Required |
_externalKeyFields | Array | The fields that form the external key, as a non-empty array of field names. Must be the same for every element of a class. Omit it, or send null, to use the key declared on the class. Under UPSERT, a class with no key fields, sent or declared, fails. | Optional |
_name | String | The display name. Must be a non-blank string or null. Any other value fails validation for the element's class. | Optional |
_relationships | Array | An array of relationship objects from this individual, in import form or native form. See the following table. | Optional |
Any other field is stored on the item, as in Create individuals.
External keys have the form field=value, with several pairs joined by |, for example "_sourceKey=r-1". The service doesn't store this combined key. Under UPSERT, and for _parentExternalKey and _childExternalKeys, it matches existing individuals on the _externalKeyFields themselves, at the path you sent them. A number matches its text form. A real import also asks the Item Service to index those fields on each class's collection. To find an imported individual, search on its key field. A blank key, a key that appears twice in the payload, or a key that matches more than one existing individual makes that element a conflict. A conflicting element isn't written, and the import doesn't conform.
Each _relationships entry uses one of two forms:
| Form | Fields | Targets |
|---|---|---|
| Import form | _propertyName; _parentIndividualId or _parentExternalKey; _childIndividualIds, _childExternalKeys, or both. _childExternalKeys needs _targetClassId. | Can be individuals created by the same request. |
| Native form | _userType, _relatedToIds, and optional _customAttributes, as in Create individuals. | Must already exist. On an existing individual, the entries replace its stored relationships of each _userType you send. |
Note: Import-form relationships replace. After all classes are written, the import sets each parent and property to exactly the targets you name, so naming one target for an existing individual removes its other relationships of that type. Send the complete set of targets. An empty
_childExternalKeysremoves all of them. A rollback doesn't restore removed relationships, and a dry run skips this step.
An import-form relationship with at least one target counts toward a required relationship of its source. So you can import an individual and its required relationship in the same request.
Example:
[
{
"_classId": "5e7f9a1b-3c2d-4e6f-8a0b-1c3d5e7f9a20",
"_externalKeyFields": ["_sourceKey"],
"_sourceKey": "r-1",
"_name": "Room 1"
},
{
"_classId": "3f6c1a52-8d0e-4b7a-9c4f-2e1d5b8a7c90",
"_externalKeyFields": ["_sourceKey"],
"_sourceKey": "p-1",
"_name": "Pump A",
"properties": { "flowRate": 42.5 },
"_relationships": [
{
"_propertyName": "locatedAt",
"_parentExternalKey": "_sourceKey=p-1",
"_childExternalKeys": ["_sourceKey=r-1"],
"_targetClassId": "5e7f9a1b-3c2d-4e6f-8a0b-1c3d5e7f9a20"
}
]
}
]
Response
A queued import returns 202 with a Location header that points at /aosvc/api/v1/async-tasks/{taskId}.
{
"_taskId": "9a1e5f7c-4b2d-4e8a-b6c3-0d7f1e9a2b54",
"_status": "QUEUED",
"_classesQueued": 2,
"_individualsQueued": 2
}
A dry run returns the full result document. In each _classes entry, _plan lists one decision per element. _action is CREATE, UPDATE, SKIP, or CONFLICT. _validation appears when a class fails validation.
{
"_dryRun": true,
"_conforms": true,
"_modelRevision": 7,
"_classesProcessed": 2,
"_totalIndividualsCreated": 0,
"_totalIndividualsUpdated": 0,
"_totalIndividualsSkipped": 0,
"_totalConflicts": 0,
"_totalIssues": 0,
"_classes": [
{
"_classId": "3f6c1a52-8d0e-4b7a-9c4f-2e1d5b8a7c90",
"_requested": 1,
"_created": 0,
"_updated": 0,
"_skipped": 0,
"_conflicts": 0,
"_externalKeyFields": ["_sourceKey"],
"_plan": [
{
"_externalKey": "_sourceKey=p-1",
"_action": "CREATE",
"_individualId": "6702a9f3c1e4b2001f9a1c21"
}
],
"_createdIds": ["6702a9f3c1e4b2001f9a1c21"],
"_conforms": true
}
]
}
Codes
| Code | Description |
|---|---|
200 | Success. Dry run only: the data conforms. |
202 | Accepted. The import is queued. |
400 | Bad Request. The body isn't a non-empty JSON array or isn't valid JSON, an element has no _classId, _externalKeyFields isn't a non-empty array of field names or differs within a class, _relationships isn't an array of objects, an import-form relationship has a blank _propertyName, no parent, or _childExternalKeys without _targetClassId, dryRun or rollback isn't a Boolean, or nsfilter is missing. On a dry run, also a bad mode or facets value. |
401 | Unauthorized |
403 | Forbidden. A class is missing an INDIVIDUALS_CREATE or INDIVIDUALS_EDIT grant. |
404 | Not Found. Queued import: a _classId isn't in the live version or has no collection mapping, or a _targetClassId isn't in the ontology. Any import: nsfilter names a namespace outside the ontology. |
409 | Conflict. Queued import: the ontology has no live version, or a class's mapping has no collection. |
413 | Payload Too Large. The body is over 10 MB. |
422 | Unprocessable Entity. Dry run only: the data doesn't conform. The body is the result document. |
503 | Service Unavailable. The service couldn't store the request. Nothing was queued; retry. |
Get an async task
Gets the status of a queued job, such as an import, by its task ID. You can read any task in the namespaces that nsfilter names. Fields with no value are omitted.
_status is the task's state, not its verdict. A job that rejects its data still ends COMPLETED. Read the verdict in _response._body.
_status | Meaning |
|---|---|
CREATED, QUEUED, IN_PROGRESS, RESET | Waiting or running. RESET means the job was interrupted and queued again. Keep polling. |
COMPLETED | The job finished. Read the verdict in _response._body. |
FAILED | The job itself failed. Read the reason in _detailedStatus. |
_response._body._handler names the kind of job:
_handler | Raised by | Verdict |
|---|---|---|
ONTOLOGY_IMPORT | Import individuals | _conforms |
RELATIONSHIP_BULK_ADD | Add relationships in bulk | _accepted. Poll Get a bulk relationship task instead, which also reports the Item Service write. |
INDIVIDUAL_PERMISSION_RECONCILE | Class, mapping, and permission changes that return an X-AOSVC-Reconciliation-Task-Id header | None. The job either ran or is FAILED. |
| None | Confirming a promotion request | The body is the promotion outcome. Read the verdict on the promotion request. |
Endpoints
GET /aosvc/api/v1/async-tasks/{taskId}
Parameters
Path
| Parameter | Type | Description | Required |
|---|---|---|---|
taskId | String | The task ID. | Required |
Query
| Parameter | Type | Description | Required |
|---|---|---|---|
nsfilter | String | The namespace filter. The task must belong to one of these namespaces. | Required |
Response
_batchCompleted counts the class groups an import has finished. _timeTakenInMilliSecs has whole-second precision. _response appears only once the task is COMPLETED or FAILED. _response._status is the job's HTTP status: 200 for any job that ran to the end, 400 for input the job refused, and 500 otherwise.
{
"_id": "9a1e5f7c-4b2d-4e8a-b6c3-0d7f1e9a2b54",
"_status": "COMPLETED",
"_batchCompleted": 2,
"_reqBodySize": 412,
"_timeTakenInMilliSecs": 1000,
"_namespaces": ["myapp_Xw6AQru7"],
"_metadata": {
"_createdAt": "2026-10-20T10:00:00Z",
"_createdById": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_updatedAt": "2026-10-20T10:00:01Z"
},
"_response": {
"_status": 200,
"_statusMsg": "SUCCESS",
"_body": {
"_handler": "ONTOLOGY_IMPORT",
"_asyncTaskId": "9a1e5f7c-4b2d-4e8a-b6c3-0d7f1e9a2b54",
"_conforms": true,
"_modelRevision": 7,
"_classesProcessed": 2,
"_totalIndividualsCreated": 2,
"_totalIndividualsUpdated": 0,
"_totalIndividualsSkipped": 0,
"_totalConflicts": 0,
"_totalIssues": 0,
"_classes": [
{
"_classId": "3f6c1a52-8d0e-4b7a-9c4f-2e1d5b8a7c90",
"_requested": 1,
"_created": 1,
"_updated": 0,
"_skipped": 0,
"_conflicts": 0,
"_conforms": true
},
{
"_classId": "5e7f9a1b-3c2d-4e6f-8a0b-1c3d5e7f9a20",
"_requested": 1,
"_created": 1,
"_updated": 0,
"_skipped": 0,
"_conflicts": 0,
"_conforms": true
}
],
"_relationships": {
"_requestedEdges": 1,
"_parentsUpdated": 1,
"_edgesSet": 1
}
}
}
}
The import report has counts only. For conflict reasons and validation violations, run the import as a dry run. When an import rolled back, the report includes _rollback. When the task is FAILED, _response._body holds only _error, the reason.
Codes
| Code | Description |
|---|---|
200 | Success |
400 | Bad Request. The task ID is malformed, or nsfilter is missing. |
401 | Unauthorized |
404 | Not Found. No task with this ID exists in your namespaces. |
Undo an import
Deletes the individuals that an import created. Use it after an import that ran with rollback=false, or to remove an import's data later. Deleting an individual also deletes its relationships.
The service searches the classes that the import wrote to, and finds individuals by the import's task ID stamp. If the service no longer has the import's task, it searches every class of the ontology. An individual that the import only updated isn't selected. An individual the import created is still found after a later update. The call doesn't restore _externalKeyFields.
The deletes run asynchronously in the Item Service. The response says what the service sent, not that the deletes finished. A task ID that matches nothing deletes nothing and returns 200 with an empty _dispatched.
You need INDIVIDUALS_DELETE on every class that the service searches. If any class denies it, the call returns 403 and deletes nothing.
Endpoints
DELETE /aosvc/api/v1/ontologies/{ontologyId}/import/{asyncTaskId}
Parameters
Path
| Parameter | Type | Description | Required |
|---|---|---|---|
ontologyId | String | The ID of the application ontology. | Required |
asyncTaskId | String | The _taskId that the import returned. | Required |
Query
| Parameter | Type | Description | Required |
|---|---|---|---|
nsfilter | String | The namespace filter. Must name only namespaces the ontology belongs to. | Required |
Response
| Field | Description |
|---|---|
_classesSearched | The number of classes searched. |
_dispatched | One entry per class the service sent a delete for, with the class ID, collection ID, and Item Service task ID. |
_classesWithoutMapping | Classes skipped because they have no collection mapping or no collection. |
_classesWithoutMatches | Mapped classes where no individual carries the stamp. No delete was sent. |
_errors | Per-class failures, as "<classId>: <reason>". The other classes still ran. |
{
"_asyncTaskId": "9a1e5f7c-4b2d-4e8a-b6c3-0d7f1e9a2b54",
"_ontologyId": "1c3e5a7b-9d2f-4b6a-8c0e-2f4a6b8d0c13",
"_classesSearched": 3,
"_dispatched": [
{
"_classId": "3f6c1a52-8d0e-4b7a-9c4f-2e1d5b8a7c90",
"_collectionId": "6702a8e1c1e4b2001f9a1b10",
"_itemsvcTaskId": "3c8e1f5a-7b2d-4e9a-8f6c-0a4d2b6e8c13"
},
{
"_classId": "5e7f9a1b-3c2d-4e6f-8a0b-1c3d5e7f9a20",
"_collectionId": "6702a8e1c1e4b2001f9a1b22",
"_itemsvcTaskId": "5d0a2c7e-9f4b-4a1c-b8e3-2c6f4d8a0e25"
}
],
"_classesWithoutMapping": [],
"_classesWithoutMatches": ["9b2d4e6f-8a1c-4b3d-9e5f-7a6b8c0d1e23"],
"_errors": []
}
Codes
| Code | Description |
|---|---|
200 | Success |
400 | Bad Request. The task ID is blank, or nsfilter is missing. |
401 | Unauthorized |
403 | Forbidden. A class that the service searches is missing an INDIVIDUALS_DELETE grant. |
404 | Not Found. nsfilter names a namespace outside the ontology. |
409 | Conflict. The ontology has no live version. |
Add relationships in bulk
Adds many relationships from individuals of a class in one asynchronous request. Unlike Replace relationships for many individuals, this call adds to the stored relationships and doesn't replace them.
The call returns 202 once the service stores the batch. Validation and the write happen later, so a data fault never comes back as an HTTP status here. To get the outcome, poll Get a bulk relationship task. If validation finds any fault, nothing is written.
You need INDIVIDUALS_EDIT on the class or an ancestor.
Endpoints
POST /aosvc/api/v1/classes/{classId}/individuals/relationships/bulk
Parameters
Path
| Parameter | Type | Description | Required |
|---|---|---|---|
classId | String | The ID of the source individuals' class. | Required |
Query
| Parameter | Type | Description | Required |
|---|---|---|---|
nsfilter | String | The namespace filter. Must name only namespaces the class's ontology belongs to. | Required |
Body
A non-empty JSON array of entries. Each source must be an individual of this class or its subclasses. Entries with the same source and _userType are combined into one relationship, unless their _customAttributes differ.
| Parameter | Type | Description | Required |
|---|---|---|---|
_userType | String | The name of the relationship. | Required |
_relatedFromId | String | The ID of the source individual. | Required |
_relatedToIds | Array | The IDs of the target individuals. | Required |
_customAttributes | Object | A flat map of key-value pairs on the relationship. | Optional |
Example:
[
{
"_userType": "locatedAt",
"_relatedFromId": "6702a9f3c1e4b2001f9a1c21",
"_relatedToIds": ["6702a9f3c1e4b2001f9a1d40"]
},
{
"_userType": "feeds",
"_relatedFromId": "6702a9f3c1e4b2001f9a1c21",
"_relatedToIds": ["6702a9f3c1e4b2001f9a1c35", "6702a9f3c1e4b2001f9a1c36"],
"_customAttributes": { "installedYear": 2020 }
}
]
Response
The Location header points at this batch's poll route, /aosvc/api/v1/classes/{classId}/individuals/relationships/bulk/{taskId}.
{
"_taskId": "c47d2e10-8f3a-4b6c-9d1e-5a7b9c0d2e43",
"_status": "QUEUED",
"_entriesAccepted": 2
}
Codes
| Code | Description |
|---|---|
202 | Accepted |
400 | Bad Request. The body isn't a non-empty JSON array or isn't valid JSON, or nsfilter is missing. |
401 | Unauthorized |
403 | Forbidden. No INDIVIDUALS_EDIT grant, or the class is a lifecycle class. |
404 | Not Found. The class isn't in the live version, has no collection mapping, or nsfilter names a namespace outside the ontology. |
409 | Conflict. The ontology has no live version, or the live mapping has no collection. |
413 | Payload Too Large. The body is over 10 MB, or the batch is too large for one Item Service request (8 MB by default, counting about 160 bytes of overhead per entry). Split it into smaller batches. |
503 | Service Unavailable. The service couldn't store the batch. Nothing was queued; retry. |
Get a bulk relationship task
Gets the status and verdict of a bulk relationship batch. Poll this route rather than Get an async task, which reports COMPLETED as soon as the batch passes to the Item Service. Fields with no value are omitted.
_status | _accepted | Meaning |
|---|---|---|
CREATED, QUEUED, IN_PROGRESS, RESET | Absent | Waiting or validating. Nothing is written yet. |
COMPLETED | false | The batch was refused. Read _error, _errorStatus, and _issues. Nothing was written. |
The Item Service task status: IN_PROGRESS, then COMPLETED or FAILED | true | The batch passed validation and went to the Item Service. Only COMPLETED means the relationships are written. |
COMPLETED | true | The batch passed validation, but every relationship was already stored, so nothing was sent. _itemsvcTaskId is absent. |
FAILED | Absent | An unexpected error or a dependency failure. The reason is in _error. An unknown amount may be written; a retry may succeed. |
Each entry in _issues has _entryIndex (zero-based), _check, _status, _message, and where relevant the _userType, _relatedFromId, or _relatedToId at fault. _check is one of ENTRY_SHAPE, ENTRY_MISSING_SOURCE, RELATIONSHIP_NOT_DECLARED, TARGET_CLASS_UNBOUND, SOURCE_NOT_FOUND, SOURCE_WRONG_CLASS, TARGET_NOT_FOUND, or FUNCTIONAL_EXCEEDED. The list holds up to 100 issues. At that limit validation stops, _issuesTruncated is true, and _issueCount is a lower bound.
On an accepted batch, _recordsSubmitted counts the relationship records sent, _edgesSubmitted counts new relationships, and _edgesAlreadyStored counts relationships the sources already had.
Endpoints
GET /aosvc/api/v1/classes/{classId}/individuals/relationships/bulk/{taskId}
Parameters
Path
| Parameter | Type | Description | Required |
|---|---|---|---|
classId | String | The ID of the source individuals' class. | Required |
taskId | String | The _taskId that Add relationships in bulk returned. An Item Service task ID from _itemsvcTaskId also works. | Required |
Query
| Parameter | Type | Description | Required |
|---|---|---|---|
nsfilter | String | The namespace filter. The task must belong to one of these namespaces. | Required |
Response
A refused batch:
{
"_taskId": "c47d2e10-8f3a-4b6c-9d1e-5a7b9c0d2e43",
"_entriesAccepted": 4,
"_status": "COMPLETED",
"_error": "3 issues found while validating 4 entries — nothing was written. See _issues.",
"_errorStatus": 400,
"_issueCount": 3,
"_issues": [
{
"_entryIndex": 1,
"_check": "RELATIONSHIP_NOT_DECLARED",
"_status": 400,
"_message": "No relationship 'ownedBy' is declared from class 'Pump'",
"_userType": "ownedBy"
}
],
"_accepted": false
}
An accepted batch. _itemsvcTask is the Item Service task as the Item Service returns it, shortened here.
{
"_taskId": "c47d2e10-8f3a-4b6c-9d1e-5a7b9c0d2e43",
"_entriesAccepted": 2,
"_accepted": true,
"_recordsSubmitted": 2,
"_edgesSubmitted": 3,
"_edgesAlreadyStored": 0,
"_itemsvcTaskId": "b7e3c9a1-4d2f-4a8e-9c6b-1f0d3e5a7c92",
"_status": "COMPLETED",
"_itemsvcTask": {
"_id": "b7e3c9a1-4d2f-4a8e-9c6b-1f0d3e5a7c92",
"_status": "COMPLETED"
}
}
Codes
| Code | Description |
|---|---|
200 | Success |
400 | Bad Request. The task ID isn't a UUID, or nsfilter is missing. |
401 | Unauthorized |
403 | Forbidden. No INDIVIDUALS_READ grant on the class or an ancestor. |
404 | Not Found. No bulk task with this ID exists in your namespaces, or nsfilter names a namespace outside the ontology. |