> ## Documentation Index > Fetch the complete documentation index at: https://docs.getmodus.com/llms.txt > Use this file to discover all available pages before exploring further. # Create custom context items > Creates or updates a batch of customer-owned custom context items. Batch imports are idempotent by source, collection, entity, and field identifiers. **Requires:** `context:write` ## OpenAPI ````yaml https://api.getmodus.com/openapi.json post /api/v1/context/custom-items/batch openapi: 3.0.3 info: title: Modus Public API version: 1.0.0 servers: [] security: - bearerAuth: [] tags: - name: Scopes description: Create, configure, deploy, and manage scopes. - name: Scopes · Conversations description: Read scope conversation threads. - name: Scopes · Supervision description: Scope supervision sub-resource. - name: Scopes · Memories description: Long-term memory stored per scope. - name: Scopes · Chat description: Chat with a published scope. - name: Scopes · Context description: Compose a scope’s context without an LLM call. - name: Modus · Chat description: Chat with Modus — your org-wide assistant. - name: Modus · Conversations description: Read Modus and cross-scope conversation threads. - name: Modus · Context description: Compose full-environment context without an LLM call. - name: Workflows description: Create, configure, deploy, and manage workflows. - name: Workflows · Runs description: Inspect workflow run history. - name: Workflows · Interfaces description: Slack / MCP / Teams interface management. - name: Connections description: Read connected integrations. - name: Tools description: Catalog of tools/integrations a scope can select in its toolset. - name: Suggestions description: Approved suggested questions and first-party suggestion usage events. - name: Context description: Create and manage organization context items. - name: Usage description: Organization LLM usage reporting. - name: Users description: Organization and membership management. - name: Runs · Streaming description: 'Run lifecycle: stream, poll, resume, interrupt, and cancel executions.' - name: Scopes · Runs description: Run a published or draft scope. - name: Modus · Runs description: Run the Modus home agent. paths: /api/v1/context/custom-items/batch: post: tags: - Context summary: Create custom context items description: >- Creates or updates a batch of customer-owned custom context items. Batch imports are idempotent by source, collection, entity, and field identifiers. **Requires:** `context:write` operationId: CustomContextItemsController_batchCreate parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BatchCreateCustomContextItemsDto' examples: entities: value: items: - kind: entity sourceId: billing-db sourceName: Billing database collectionId: contracts collectionName: Contracts externalId: contract-123 name: Acme renewal contract entityType: contract description: >- Enterprise renewal metadata from the internal billing system. attributes: - name: status dataType: string value: text: active topics: - billing - renewals responses: '201': description: '' content: application/json: schema: $ref: '#/components/schemas/BatchCreateCustomContextItemsResponseDto' '400': description: >- Malformed request — invalid query parameters or request body (`code: BAD_REQUEST`). content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' example: error: code: BAD_REQUEST status: INVALID_ARGUMENT message: Invalid value for query parameter `pageSize`. requestId: req_01HQ7K8ABCDEFGHIJKLMNOPQRS '401': description: 'Missing, invalid, or expired access token (`code: UNAUTHORIZED`).' content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' example: error: code: UNAUTHORIZED status: UNAUTHENTICATED message: Missing or invalid access token. requestId: req_01HQ7K8ABCDEFGHIJKLMNOPQRS '403': description: >- Authenticated, but the token lacks a required scope (`code: FORBIDDEN`). The missing scopes are listed in `info`. content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' example: error: code: FORBIDDEN status: PERMISSION_DENIED message: Missing required scope(s) for this operation. requestId: req_01HQ7K8ABCDEFGHIJKLMNOPQRS info: missing: - '404': description: >- The resource does not exist, or you do not have access to it (`code: NOT_FOUND`). content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' example: error: code: NOT_FOUND status: NOT_FOUND message: Resource not found. requestId: req_01HQ7K8ABCDEFGHIJKLMNOPQRS '409': description: >- The request conflicts with the current state of the resource, e.g. a duplicate (`code: CONFLICT`). content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' example: error: code: CONFLICT status: ALREADY_EXISTS message: A resource with that identifier already exists. requestId: req_01HQ7K8ABCDEFGHIJKLMNOPQRS '422': description: >- The request was well-formed but failed a business rule (`code: VALIDATION`). content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' example: error: code: VALIDATION status: INVALID_ARGUMENT message: Updates that would revoke your own access are not allowed. requestId: req_01HQ7K8ABCDEFGHIJKLMNOPQRS '500': description: 'An unexpected server error occurred (`code: INTERNAL_ERROR`).' content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' example: error: code: INTERNAL_ERROR status: INTERNAL message: An unexpected error occurred. requestId: req_01HQ7K8ABCDEFGHIJKLMNOPQRS security: - bearerAuth: [] servers: - url: https://api.getmodus.com components: schemas: BatchCreateCustomContextItemsDto: type: object properties: items: description: >- Custom context items to upsert. Batch imports are idempotent by item hierarchy. type: array items: $ref: '#/components/schemas/CreateCustomContextItemDto' required: - items BatchCreateCustomContextItemsResponseDto: type: object properties: contextItems: description: Custom context items created or updated by the batch. type: array items: $ref: '#/components/schemas/CreatedCustomContextItemResponseDto' required: - contextItems ErrorResponseDto: type: object properties: error: $ref: '#/components/schemas/ErrorEnvelopeDto' required: - error CreateCustomContextItemDto: type: object properties: kind: description: Shape of custom context item to create. example: entity allOf: - $ref: '#/components/schemas/CustomContextItemKind' sourceId: type: string description: Stable identifier for the customer-defined source. example: billing-db sourceName: type: string description: Display name for the customer-defined source. example: Billing database collectionId: type: string description: Stable identifier for the collection inside the source. example: contracts collectionName: type: string description: Display name for the collection. example: Contracts externalId: type: string description: Stable identifier for the entity inside the collection. example: contract-123 fieldName: type: string description: Field name for field-level custom context. example: renewalDate name: type: string description: Display name for the item. example: Acme renewal contract entityType: type: string description: Customer-defined entity or field type. example: contract description: type: string description: Human-readable description. example: >- Enterprise contract renewal metadata from the internal billing system. content: type: object description: Main textual or structured content for the custom item. additionalProperties: true url: type: string description: Customer-facing URL for the source object, when available. example: https://internal.example.com/contracts/contract-123 attributes: description: Structured attributes for entity-level custom context. type: array items: $ref: '#/components/schemas/CustomAttributeDto' dataType: type: string description: Field data type for field-level custom context. example: timestamp value: type: object description: Representative value for field-level custom context. additionalProperties: true samples: description: Representative samples for entity sample context. type: array items: type: object raw: type: object additionalProperties: true description: >- Customer-specific fields that should be retained but are not part of the normalized contract. topics: description: Topic tags for filtering. example: - billing - renewals type: array items: type: string idempotencyKey: type: string description: Optional stable key used to make single-item creates idempotent. example: billing-db/contracts/contract-123 access: $ref: '#/components/schemas/AccessPolicyDto' required: - kind - sourceId CreatedCustomContextItemResponseDto: type: object properties: contextItemId: type: string description: Stable uid of the created or updated custom context item. example: 7a3f9d2c-1111-4000-a000-000000000abc contextType: type: string description: Stored custom context type. example: custom_entity_metadata dataPath: description: Hierarchical path used to group custom context. example: - billing-db - contracts - contract-123 type: array items: type: string title: type: string description: Display title resolved for the item. nullable: true example: Acme renewal contract required: - contextItemId - contextType - dataPath - title ErrorEnvelopeDto: type: object properties: code: description: Modus-specific machine code. allOf: - $ref: '#/components/schemas/ApiErrorCode' status: description: Canonical status string for the error. allOf: - $ref: '#/components/schemas/ApiErrorStatus' message: type: string example: Skill was not found or you lack permission. requestId: type: string example: req_01HQ7K8ABCDEFGHIJKLMNOPQRS info: type: object description: >- Optional domain-specific context. Shape varies per endpoint — see the operation's error response examples. additionalProperties: true example: skillId: sk_abc123 required: - code - status - message - requestId CustomContextItemKind: type: string enum: - source - collection - entity - field - entity_samples description: Shape of custom context item to create. CustomAttributeDto: type: object properties: name: type: string description: Attribute name. example: status dataType: type: string description: Customer-defined attribute type. example: string value: type: object description: Representative value for this attribute. additionalProperties: true required: - name AccessPolicyDto: type: object properties: scope: type: string enum: - all - groups - users default: all description: Visibility mode. Defaults to org-wide ("all") when omitted. groupIds: description: Member group uuids granted access. Required when scope is "groups". type: array items: type: string userIds: description: Clerk user ids granted access. Required when scope is "users". type: array items: type: string ApiErrorCode: type: string enum: - VALIDATION - BAD_REQUEST - UNAUTHORIZED - FORBIDDEN - NOT_FOUND - CONFLICT - RATE_LIMITED - INTERNAL_ERROR description: Modus-specific machine code. ApiErrorStatus: type: string enum: - INVALID_ARGUMENT - UNAUTHENTICATED - PERMISSION_DENIED - NOT_FOUND - ALREADY_EXISTS - RESOURCE_EXHAUSTED - INTERNAL description: Canonical status string for the error. securitySchemes: bearerAuth: scheme: bearer bearerFormat: Modus PAT (modus___) or OAuth 2.1 access token type: http description: >- A Modus personal access token (`modus___`) or an OAuth 2.1 access token, sent as `Authorization: Bearer `. ````