/api/v2/knowledge/imports/{importId}Get an import's progress and outcome. During uploading, the signed upload token is required; omitting it returns 404.
OAuth scope: api:read.
Authentication
Send a personal or workspace API key in X-API-Key. See key types and access; operations that reject workspace keys say so in their description.
Send X-API-Key in the request header.
Alternatively
Send a Sim OAuth access token in Authorization: Bearer. See OAuth authentication and scopes.
Authorization: Bearer YOUR_ACCESS_TOKEN
Required scopes: api:read
OAuth flows
OAuth scope: api:read.
Path parameters
Unique knowledge-base import identifier.
- minLength
- 1
Query parameters
Workspace that owns the import.
- minLength
- 1
- maxLength
- 128
Header parameters
Signed upload control token returned when the import was created; required to read or cancel the import before its upload completes.
- minLength
- 1
Responses
200
The requested knowledge base import.
A knowledge base import lifecycle resource.
1 field
Response data.
13 fields
Unique knowledge-base import identifier.
Workspace that owns the import.
Current import lifecycle state.
- enum
- ["uploading","processing","completed","failed","canceled","expired"]
Knowledge base the import created, or null until it exists.
Schema details
Any of
Documents the bundle carries; zero until its manifest has been read.
- minimum
- 0
- maximum
- 9007199254740991
Documents created so far. A document whose vectors could not be reused is indexed afterwards, as an upload is, so it may still be processing in the knowledge base.
- minimum
- 0
- maximum
- 9007199254740991
Documents that could not be imported. Non-zero still allows completed.
- minimum
- 0
- maximum
- 9007199254740991
Whether the bundle's vectors matched this deployment's embedding model and were stored without re-embedding.
Bounded sample of the documents that could not be imported.
Schema details
One bundle document the import could not bring over.
2 fields
Filename of the document that was not imported.
Why the document was not imported.
Additional properties are not allowed.
Terminal failure reason, or null.
Schema details
Any of
ISO 8601 creation timestamp.
- format
- date-time
- pattern
- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
ISO 8601 last-update timestamp.
- format
- date-time
- pattern
- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
ISO 8601 completion timestamp, or null.
Schema details
Any of
- format
- date-time
- pattern
- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
Additional properties are not allowed.
Additional properties are not allowed.
Response headers
Maximum requests allowed in the current window.
- minimum
- 0
- maximum
- 9007199254740991
Requests remaining in the current window.
- minimum
- 0
- maximum
- 9007199254740991
ISO 8601 timestamp when the current rate-limit window resets.
- format
- date-time
- pattern
- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
400
The request is invalid. This includes a query parameter sent with no value (?limit=, ?search=), which is rejected rather than read as zero, empty, or the parameter default — omit the parameter instead.
Canonical error envelope returned by the public v2 API.
1 field
Canonical error details.
3 fields
Stable machine-readable error code.
Human-readable explanation of the error.
Structured error context whose keys depend on the error. Actionable 403 responses use the V2ActionableForbiddenDetails shape; validation failures may return issue arrays instead.
Schema details
Any of
Machine-readable cause and optional context for an actionable 403 response.
1 field
Stable cause code for an actionable 403 response.
- enum
- ["INSUFFICIENT_WORKSPACE_ROLE","PERSONAL_API_KEYS_DISABLED","WORKSPACE_KEY_OPERATION_NOT_PERMITTED","PRINCIPAL_KIND_NOT_PERMITTED","ORGANIZATION_MEMBERSHIP_REQUIRED","ORGANIZATION_ADMIN_REQUIRED","ENTERPRISE_PLAN_REQUIRED","SSO_DISABLED","SSO_DOMAIN_NOT_VERIFIED","SSO_PROVIDER_LIMIT_REACHED","ORGANIZATION_PLAN_REQUIRED","AUDIT_LOGS_DISABLED","ACCESS_REQUESTS_DISABLED","ACCESS_REQUEST_ORGANIZATION_REQUIRED","SKILL_EDITOR_ACCESS_REQUIRED","SECRET_ADMIN_ACCESS_REQUIRED","WORKSPACE_RESOURCE_LIMIT_REACHED","PUBLIC_SHARING_NOT_ALLOWED","CREDENTIAL_ADMIN_ACCESS_REQUIRED","MCP_SERVER_URL_NOT_ALLOWED","WORKSPACE_PLAN_CAPABILITY_REQUIRED","CHAT_AUTH_MODE_NOT_PERMITTED","CONNECTOR_MANAGED_RESOURCE_READ_ONLY","PERMISSION_GROUP_CAPABILITY_BLOCKED","INTEGRATION_NOT_ALLOWED","INSUFFICIENT_SCOPE","SCIM_MANAGED_MEMBERSHIP"]
Additional context for this refusal.
Other structured context defined by the specific error.
Additional properties are not allowed.
Additional properties are not allowed.
401
The API credential is missing or invalid.
Canonical error envelope returned by the public v2 API.
1 field
Canonical error details.
3 fields
Stable machine-readable error code.
Human-readable explanation of the error.
Structured error context whose keys depend on the error. Actionable 403 responses use the V2ActionableForbiddenDetails shape; validation failures may return issue arrays instead.
Schema details
Any of
Machine-readable cause and optional context for an actionable 403 response.
1 field
Stable cause code for an actionable 403 response.
- enum
- ["INSUFFICIENT_WORKSPACE_ROLE","PERSONAL_API_KEYS_DISABLED","WORKSPACE_KEY_OPERATION_NOT_PERMITTED","PRINCIPAL_KIND_NOT_PERMITTED","ORGANIZATION_MEMBERSHIP_REQUIRED","ORGANIZATION_ADMIN_REQUIRED","ENTERPRISE_PLAN_REQUIRED","SSO_DISABLED","SSO_DOMAIN_NOT_VERIFIED","SSO_PROVIDER_LIMIT_REACHED","ORGANIZATION_PLAN_REQUIRED","AUDIT_LOGS_DISABLED","ACCESS_REQUESTS_DISABLED","ACCESS_REQUEST_ORGANIZATION_REQUIRED","SKILL_EDITOR_ACCESS_REQUIRED","SECRET_ADMIN_ACCESS_REQUIRED","WORKSPACE_RESOURCE_LIMIT_REACHED","PUBLIC_SHARING_NOT_ALLOWED","CREDENTIAL_ADMIN_ACCESS_REQUIRED","MCP_SERVER_URL_NOT_ALLOWED","WORKSPACE_PLAN_CAPABILITY_REQUIRED","CHAT_AUTH_MODE_NOT_PERMITTED","CONNECTOR_MANAGED_RESOURCE_READ_ONLY","PERMISSION_GROUP_CAPABILITY_BLOCKED","INTEGRATION_NOT_ALLOWED","INSUFFICIENT_SCOPE","SCIM_MANAGED_MEMBERSHIP"]
Additional context for this refusal.
Other structured context defined by the specific error.
Additional properties are not allowed.
Additional properties are not allowed.
403
The caller lacks the rights this operation requires. When the cause is one a caller can act on, error.details.code names it. A resource in a workspace the caller cannot reach at all answers 404 instead, so absence and denial are indistinguishable.
Canonical error envelope returned by the public v2 API.
1 field
Canonical error details.
3 fields
Stable machine-readable error code.
Human-readable explanation of the error.
Structured error context whose keys depend on the error. Actionable 403 responses use the V2ActionableForbiddenDetails shape; validation failures may return issue arrays instead.
Schema details
Any of
Machine-readable cause and optional context for an actionable 403 response.
1 field
Stable cause code for an actionable 403 response.
- enum
- ["INSUFFICIENT_WORKSPACE_ROLE","PERSONAL_API_KEYS_DISABLED","WORKSPACE_KEY_OPERATION_NOT_PERMITTED","PRINCIPAL_KIND_NOT_PERMITTED","ORGANIZATION_MEMBERSHIP_REQUIRED","ORGANIZATION_ADMIN_REQUIRED","ENTERPRISE_PLAN_REQUIRED","SSO_DISABLED","SSO_DOMAIN_NOT_VERIFIED","SSO_PROVIDER_LIMIT_REACHED","ORGANIZATION_PLAN_REQUIRED","AUDIT_LOGS_DISABLED","ACCESS_REQUESTS_DISABLED","ACCESS_REQUEST_ORGANIZATION_REQUIRED","SKILL_EDITOR_ACCESS_REQUIRED","SECRET_ADMIN_ACCESS_REQUIRED","WORKSPACE_RESOURCE_LIMIT_REACHED","PUBLIC_SHARING_NOT_ALLOWED","CREDENTIAL_ADMIN_ACCESS_REQUIRED","MCP_SERVER_URL_NOT_ALLOWED","WORKSPACE_PLAN_CAPABILITY_REQUIRED","CHAT_AUTH_MODE_NOT_PERMITTED","CONNECTOR_MANAGED_RESOURCE_READ_ONLY","PERMISSION_GROUP_CAPABILITY_BLOCKED","INTEGRATION_NOT_ALLOWED","INSUFFICIENT_SCOPE","SCIM_MANAGED_MEMBERSHIP"]
Additional context for this refusal.
Other structured context defined by the specific error.
Additional properties are not allowed.
Additional properties are not allowed.
404
The requested resource was not found.
Canonical error envelope returned by the public v2 API.
1 field
Canonical error details.
3 fields
Stable machine-readable error code.
Human-readable explanation of the error.
Structured error context whose keys depend on the error. Actionable 403 responses use the V2ActionableForbiddenDetails shape; validation failures may return issue arrays instead.
Schema details
Any of
Machine-readable cause and optional context for an actionable 403 response.
1 field
Stable cause code for an actionable 403 response.
- enum
- ["INSUFFICIENT_WORKSPACE_ROLE","PERSONAL_API_KEYS_DISABLED","WORKSPACE_KEY_OPERATION_NOT_PERMITTED","PRINCIPAL_KIND_NOT_PERMITTED","ORGANIZATION_MEMBERSHIP_REQUIRED","ORGANIZATION_ADMIN_REQUIRED","ENTERPRISE_PLAN_REQUIRED","SSO_DISABLED","SSO_DOMAIN_NOT_VERIFIED","SSO_PROVIDER_LIMIT_REACHED","ORGANIZATION_PLAN_REQUIRED","AUDIT_LOGS_DISABLED","ACCESS_REQUESTS_DISABLED","ACCESS_REQUEST_ORGANIZATION_REQUIRED","SKILL_EDITOR_ACCESS_REQUIRED","SECRET_ADMIN_ACCESS_REQUIRED","WORKSPACE_RESOURCE_LIMIT_REACHED","PUBLIC_SHARING_NOT_ALLOWED","CREDENTIAL_ADMIN_ACCESS_REQUIRED","MCP_SERVER_URL_NOT_ALLOWED","WORKSPACE_PLAN_CAPABILITY_REQUIRED","CHAT_AUTH_MODE_NOT_PERMITTED","CONNECTOR_MANAGED_RESOURCE_READ_ONLY","PERMISSION_GROUP_CAPABILITY_BLOCKED","INTEGRATION_NOT_ALLOWED","INSUFFICIENT_SCOPE","SCIM_MANAGED_MEMBERSHIP"]
Additional context for this refusal.
Other structured context defined by the specific error.
Additional properties are not allowed.
Additional properties are not allowed.
429
The caller exceeded the request rate limit.
Canonical error envelope returned by the public v2 API.
1 field
Canonical error details.
3 fields
Stable machine-readable error code.
Human-readable explanation of the error.
Structured error context whose keys depend on the error. Actionable 403 responses use the V2ActionableForbiddenDetails shape; validation failures may return issue arrays instead.
Schema details
Any of
Machine-readable cause and optional context for an actionable 403 response.
1 field
Stable cause code for an actionable 403 response.
- enum
- ["INSUFFICIENT_WORKSPACE_ROLE","PERSONAL_API_KEYS_DISABLED","WORKSPACE_KEY_OPERATION_NOT_PERMITTED","PRINCIPAL_KIND_NOT_PERMITTED","ORGANIZATION_MEMBERSHIP_REQUIRED","ORGANIZATION_ADMIN_REQUIRED","ENTERPRISE_PLAN_REQUIRED","SSO_DISABLED","SSO_DOMAIN_NOT_VERIFIED","SSO_PROVIDER_LIMIT_REACHED","ORGANIZATION_PLAN_REQUIRED","AUDIT_LOGS_DISABLED","ACCESS_REQUESTS_DISABLED","ACCESS_REQUEST_ORGANIZATION_REQUIRED","SKILL_EDITOR_ACCESS_REQUIRED","SECRET_ADMIN_ACCESS_REQUIRED","WORKSPACE_RESOURCE_LIMIT_REACHED","PUBLIC_SHARING_NOT_ALLOWED","CREDENTIAL_ADMIN_ACCESS_REQUIRED","MCP_SERVER_URL_NOT_ALLOWED","WORKSPACE_PLAN_CAPABILITY_REQUIRED","CHAT_AUTH_MODE_NOT_PERMITTED","CONNECTOR_MANAGED_RESOURCE_READ_ONLY","PERMISSION_GROUP_CAPABILITY_BLOCKED","INTEGRATION_NOT_ALLOWED","INSUFFICIENT_SCOPE","SCIM_MANAGED_MEMBERSHIP"]
Additional context for this refusal.
Other structured context defined by the specific error.
Additional properties are not allowed.
Additional properties are not allowed.
Response headers
Seconds to wait before retrying, sent on 429 and 503. Add jitter rather than retrying at exactly this offset.
- minimum
- 0
- maximum
- 9007199254740991
500
An unexpected server error occurred.
Canonical error envelope returned by the public v2 API.
1 field
Canonical error details.
3 fields
Stable machine-readable error code.
Human-readable explanation of the error.
Structured error context whose keys depend on the error. Actionable 403 responses use the V2ActionableForbiddenDetails shape; validation failures may return issue arrays instead.
Schema details
Any of
Machine-readable cause and optional context for an actionable 403 response.
1 field
Stable cause code for an actionable 403 response.
- enum
- ["INSUFFICIENT_WORKSPACE_ROLE","PERSONAL_API_KEYS_DISABLED","WORKSPACE_KEY_OPERATION_NOT_PERMITTED","PRINCIPAL_KIND_NOT_PERMITTED","ORGANIZATION_MEMBERSHIP_REQUIRED","ORGANIZATION_ADMIN_REQUIRED","ENTERPRISE_PLAN_REQUIRED","SSO_DISABLED","SSO_DOMAIN_NOT_VERIFIED","SSO_PROVIDER_LIMIT_REACHED","ORGANIZATION_PLAN_REQUIRED","AUDIT_LOGS_DISABLED","ACCESS_REQUESTS_DISABLED","ACCESS_REQUEST_ORGANIZATION_REQUIRED","SKILL_EDITOR_ACCESS_REQUIRED","SECRET_ADMIN_ACCESS_REQUIRED","WORKSPACE_RESOURCE_LIMIT_REACHED","PUBLIC_SHARING_NOT_ALLOWED","CREDENTIAL_ADMIN_ACCESS_REQUIRED","MCP_SERVER_URL_NOT_ALLOWED","WORKSPACE_PLAN_CAPABILITY_REQUIRED","CHAT_AUTH_MODE_NOT_PERMITTED","CONNECTOR_MANAGED_RESOURCE_READ_ONLY","PERMISSION_GROUP_CAPABILITY_BLOCKED","INTEGRATION_NOT_ALLOWED","INSUFFICIENT_SCOPE","SCIM_MANAGED_MEMBERSHIP"]
Additional context for this refusal.
Other structured context defined by the specific error.
Additional properties are not allowed.
Additional properties are not allowed.
503
A required service is temporarily unavailable. When present, Retry-After gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before repeating a change after an uncertain response.
Canonical error envelope returned by the public v2 API.
1 field
Canonical error details.
3 fields
Stable machine-readable error code.
Human-readable explanation of the error.
Structured error context whose keys depend on the error. Actionable 403 responses use the V2ActionableForbiddenDetails shape; validation failures may return issue arrays instead.
Schema details
Any of
Machine-readable cause and optional context for an actionable 403 response.
1 field
Stable cause code for an actionable 403 response.
- enum
- ["INSUFFICIENT_WORKSPACE_ROLE","PERSONAL_API_KEYS_DISABLED","WORKSPACE_KEY_OPERATION_NOT_PERMITTED","PRINCIPAL_KIND_NOT_PERMITTED","ORGANIZATION_MEMBERSHIP_REQUIRED","ORGANIZATION_ADMIN_REQUIRED","ENTERPRISE_PLAN_REQUIRED","SSO_DISABLED","SSO_DOMAIN_NOT_VERIFIED","SSO_PROVIDER_LIMIT_REACHED","ORGANIZATION_PLAN_REQUIRED","AUDIT_LOGS_DISABLED","ACCESS_REQUESTS_DISABLED","ACCESS_REQUEST_ORGANIZATION_REQUIRED","SKILL_EDITOR_ACCESS_REQUIRED","SECRET_ADMIN_ACCESS_REQUIRED","WORKSPACE_RESOURCE_LIMIT_REACHED","PUBLIC_SHARING_NOT_ALLOWED","CREDENTIAL_ADMIN_ACCESS_REQUIRED","MCP_SERVER_URL_NOT_ALLOWED","WORKSPACE_PLAN_CAPABILITY_REQUIRED","CHAT_AUTH_MODE_NOT_PERMITTED","CONNECTOR_MANAGED_RESOURCE_READ_ONLY","PERMISSION_GROUP_CAPABILITY_BLOCKED","INTEGRATION_NOT_ALLOWED","INSUFFICIENT_SCOPE","SCIM_MANAGED_MEMBERSHIP"]
Additional context for this refusal.
Other structured context defined by the specific error.
Additional properties are not allowed.
Additional properties are not allowed.
Response headers
Seconds to wait before retrying, sent on 429 and 503. Add jitter rather than retrying at exactly this offset.
- minimum
- 0
- maximum
- 9007199254740991