> ## Documentation Index > Fetch the complete documentation index at: https://developers.datagrid.com/llms.txt > Use this file to discover all available pages before exploring further. # Create knowledge > Create knowledge which will be learned and leveraged by agents. Processing continues asynchronously after the request returns. If the background processing run later fails, subsequent retrievals surface that terminal state through `status` and `last_error`. ## Upload size limits Each file must be within your plan’s per-file size cap. If a file is too large, the API returns **413** (`payload_too_large`) with guidance and a link to [Knowledge upload limits](/knowledge/upload-limits). ## OpenAPI ````yaml post /knowledge openapi: 3.0.3 info: version: 0.1.1 title: Datagrid API description: Datagrid API servers: - url: https://api.datagrid.com/v1 security: - BearerAuth: [] paths: /knowledge: post: tags: - Knowledge summary: Create knowledge description: >- Create knowledge which will be learned and leveraged by agents. Processing continues asynchronously after the request returns. If the background processing run later fails, subsequent retrievals surface that terminal state through `status` and `last_error`. operationId: Knowledge.createKnowledge requestBody: required: true content: multipart/form-data: schema: type: object required: - files properties: name: type: string description: The name of the knowledge. nullable: true parent: $ref: '#/components/schemas/ParentObject' description: >- The parent page to nest this knowledge under. If not provided, knowledge will be created at the root level. nullable: true files: type: array items: type: string format: binary nullable: false description: >- The files to be uploaded and learned. Supported media types are `pdf`, `json`, `csv`, `text`, `png`, `jpeg`, `excel`, `google sheets`, `docx`, `pptx`. responses: '201': description: Successfully created knowledge content: application/json: schema: $ref: '#/components/schemas/Knowledge' '402': description: >- Credit limit exceeded. The organization does not have enough credits to perform this operation. Check your billing status and add credits to your account. '413': description: >- Payload too large. A file in the multipart body exceeds the per-file byte cap for the the teamspace's current plan. '429': description: >- Rate limit exceeded. The request has been throttled because the rate limit for this endpoint has been reached. Check the `Retry-After` response header and retry after the specified number of seconds. content: application/json: schema: $ref: '#/components/schemas/RateLimitError' x-codeSamples: - lang: JavaScript source: >- import Datagrid from 'datagrid-ai'; const client = new Datagrid({ apiKey: process.env['DATAGRID_API_KEY'], // This is the default and can be omitted }); const knowledge = await client.knowledge.create({ files: [fs.createReadStream('path/to/file')] }); console.log(knowledge.id); - lang: Python source: |- import os from datagrid_ai import Datagrid client = Datagrid( api_key=os.environ.get("DATAGRID_API_KEY"), # This is the default and can be omitted ) knowledge = client.knowledge.create( files=[b"Example data"], ) print(knowledge.id) components: schemas: ParentObject: type: object description: >- The parent object, indicating where the object is located in the hierarchy oneOf: - $ref: '#/components/schemas/ParentPage' - $ref: '#/components/schemas/RootPage' Knowledge: type: object description: >- The `knowledge` object represents knowledge that an agent may leverage to respond. required: - object - id - name - created_at - status - last_error - row_counts - credits - sync - parent - teamspace_id - scope properties: object: type: string enum: - knowledge description: The object type, which is always `knowledge`. id: type: string description: >- The knowledge identifier, which can be referenced in the API endpoints. name: type: string description: The name of the knowledge. teamspace_id: type: string description: The ID of the teamspace that owns this knowledge. scope: $ref: '#/components/schemas/KnowledgeScope' parent: $ref: '#/components/schemas/ParentObject' created_at: type: string format: date-time description: The ISO string for when the knowledge was created. updated_at: type: string format: date-time description: The ISO string for when the knowledge was last updated. status: $ref: '#/components/schemas/KnowledgeStatus' last_error: nullable: true description: >- The last terminal processing error for this knowledge, if any. Present when the latest asynchronous processing or re-index run ended unsuccessfully; `null` when the knowledge is `failed` only because every row ended in a persistent failed state. allOf: - $ref: '#/components/schemas/KnowledgeLastError' row_counts: type: object description: Row count statistics for the knowledge. required: - total - completed - failed properties: total: type: number description: The total number of rows in the knowledge. completed: type: number description: The number of rows successfully learned. failed: type: number description: The number of rows that failed to be processed for learning. credits: nullable: true description: >- Credit consumption for this knowledge. `null` when the knowledge is still being processed and the final cost is not yet known (e.g. immediately after creation or reindexing), or when the credit lookup fails. When present, `consumed` is the current summed spend for the knowledge's active tables — it is not necessarily the cost of the most recent request, nor the full lifetime spend. allOf: - $ref: '#/components/schemas/OperationCredits' sync: nullable: true description: Sync information for knowledge that syncs data from a connection allOf: - $ref: '#/components/schemas/KnowledgeSync' RateLimitError: type: object description: >- Returned when the rate limit is exceeded. Rate limits are enforced per teamspace, endpoint path, and HTTP method over a 60-second sliding window. Each endpoint may have its own limit — check the X-RateLimit-Limit response header for the effective value. required: - error - message - retryable - status_code properties: status_code: type: integer description: The HTTP status code (429). statusCode: type: integer deprecated: true description: Deprecated. Use status_code instead. error: type: string enum: - rate_limit_exceeded description: The error code identifying this as a rate limit error. message: type: string description: A human-readable error message. mitigation: type: string description: Suggested action to resolve the error. retryable: type: boolean description: Whether the request can be retried after a delay. details: type: object properties: reason: type: string description: A detailed explanation of why the rate limit was exceeded. ParentPage: type: object description: The parent page reference, indicating where this page is nested required: - type - page_id properties: type: type: string enum: - page description: The type of parent. 'page' indicates nested under a specific page page_id: type: string description: The ID of the parent page. Required when type is 'page' RootPage: type: object description: The root level object required: - type properties: type: type: string enum: - root description: The type of parent. 'root' indicates at the root level KnowledgeScope: type: string enum: - teamspace - organization description: >- The visibility scope of the knowledge. 'teamspace' means visible only within the owning teamspace. 'organization' means visible across all teamspaces in the same organization. KnowledgeStatus: type: string enum: - pending - partial - ready - failed description: >- The current knowledge status. `pending` indicates that processing has started but no rows have been learned yet. `partial` indicates that some rows are available, but processing is either still running or ended with incomplete results. `ready` indicates that processing finished successfully and the knowledge is fully available. `failed` indicates that no rows are currently available and the knowledge reached a terminal failure state, either because the latest asynchronous processing or re-index run ended unsuccessfully before any rows became available, or because every row ended in a persistent failed state. KnowledgeLastError: type: object required: - code - message properties: code: type: string enum: - out_of_credits - unauthorized - processing_error description: >- A machine-readable error code for the most recent terminal processing failure. message: type: string description: >- A human-readable description of the most recent terminal processing failure. OperationCredits: type: object required: - consumed properties: consumed: type: number description: The number of credits consumed by the operation. KnowledgeSync: type: object description: Sync information for knowledge that syncs data from a connection required: - connection_id - enabled properties: connection_id: type: string description: The ID of the connection used for syncing data to this knowledge example: config_123abc enabled: type: boolean description: Whether data syncing from the connection is enabled trigger: nullable: true description: >- The cron schedule configuration for syncing data from the connection. allOf: - $ref: '#/components/schemas/CronBasedTrigger' CronBasedTrigger: type: object description: A cron-based schedule for syncing data required: - type - cron_expression properties: type: type: string enum: - cron description: The trigger type, which is always `cron`. cron_expression: type: string description: Cron expression (e.g., '0 0 * * *' for daily at midnight) example: 0 0 * * * pattern: ^[0-9*/-]+ [0-9*/-]+ [0-9*/-]+ [0-9*/-]+ [0-9*/-]+$ timezone: type: string description: >- IANA timezone (e.g., 'America/New_York'). Defaults to 'UTC' if not provided. example: America/New_York default: UTC description: type: string nullable: true description: Human-readable description of the schedule securitySchemes: BearerAuth: type: http scheme: bearer ````