> ## Documentation Index > Fetch the complete documentation index at: https://help.semji.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a knowledge document > Creates a knowledge document from exactly one source: text (`content`), a web page (`url`) or a file (`fileName` and `size` in bytes). The document starts in 'pending' status while it is processed. For a file, the response also carries `upload`, a presigned S3 POST form valid for 15 minutes: send a multipart POST to `upload.url` with every `upload.fields` entry first, then the file as the `file` field, which must come last. Processing starts once the file is in storage, with no further call. Files go up to 50 MB; accepted types: pdf, csv, txt, xlsx, docx. A 403 on a file means the V2 knowledge base or direct upload is not enabled for the workspace, or the user is a guest writer: only workspace owners and members manage knowledge base files. Refusals: 400 knowledge_document_upload_type_not_allowed, 400 knowledge_document_upload_too_large, 422 knowledge_document_replacement_invalid. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/workspaces/{workspaceId}/knowledge-documents openapi: 3.0.3 info: description: > The Semji API lets you integrate Semji's AI-powered Content Marketing platform into your own tools and workflows. Scale your organic and AI visibility programmatically. ## Authentication All endpoints require a Bearer API key. Generate one from **Settings > API Keys** in the Semji app. Each key is scoped to a single user and organization. ``` Authorization: Bearer sk_your_api_key_here ``` ## Rate Limiting Requests are rate-limited per API key: **1,000 requests per hour**. Rate limit headers are included in every response: - `X-RateLimit-Limit` — Maximum requests per window - `X-RateLimit-Remaining` — Requests remaining - `X-RateLimit-Reset` — Seconds until the window resets ## Response Format All responses return JSON. Collections use a standard envelope: ```json { "data": [...], "pagination": { "total": 42, "page": 1, "limit": 25, "hasMore": true } } ``` Errors follow a consistent format: ```json { "error": { "code": "not_found", "message": "The requested resource was not found." } } ``` ## Core Concepts - **Workspace** — A single website you track. Contains pages, contents, keywords, and all related analysis data. - **Page** — A URL on your website that Semji monitors. Pages are the anchor for keywords and content drafts. - **Content** — An SEO-optimized article linked to a page. Drafts evolve through workflow statuses toward publication. - **Content Score** — A 0–100 score measuring how well your content follows Semji's SEO recommendations. Aim for 75+ before publishing. - **Keyword** — A search term tracked for a page. Analyzing a keyword produces SERP-based recommendations (topics, questions, search intents, links). - **Prompt** — A question users ask AI engines (ChatGPT, Google AI Overviews). Analyzing a prompt reveals how to optimize your content for AI citations. - **Atomic Content** — AI-powered content generation that produces a complete SEO-optimized article in one step. title: Semji API version: 1.0.0 servers: [] security: - apiKey: [] tags: - description: >- Retrieve the authenticated user and their organization, including remaining credit balances. name: Me - description: >- List members of the organization linked to the API key, with their roles (Admin or Member). name: Users - description: >- A workspace represents a single website you track in Semji. Each workspace has its own pages, contents, keywords, folders, and workflow statuses. Use these endpoints to list workspaces, view members, and access workspace-level configuration. name: Workspaces - description: >- Organize your content into a hierarchical folder structure within a workspace. Folders are returned as a flat list — reconstruct the tree client-side using `parentFolderId`. name: Folders - description: >- Pages are URLs on your website that Semji tracks for SEO performance. Import a URL to start monitoring it, trigger a crawl to fetch its metadata, and associate keywords for analysis. Each page can have content drafts attached. name: Pages - description: >- Contents are SEO-optimized articles managed through Semji. Create drafts, update them with the built-in editor or via the API, track their Content Score (0–100), and publish them to your CMS. Use Atomic Content to generate a complete optimized article with AI. The `version` field enables optimistic locking for concurrent editing. name: Contents - description: >- Track the progress of Atomic Content AI generations. After launching a generation via `POST /v1/contents/:contentId/atomic`, poll the status here. When status reaches `review`, confirm to apply the generated content to your draft, or cancel to discard it. name: Content Generations - description: >- View the credit consumption history for your organization. Credits are consumed by keyword analyses, AI content generation, and content idea searches. Each entry details what was consumed, by whom, and in which workspace. name: Credit Usages - description: >- Keywords are search terms associated with your pages. Analyzing a keyword triggers a SERP analysis that produces actionable SEO recommendations: topics to cover, questions to answer, search intents to address, and links to add. Use the report endpoint to score any content against these recommendations. name: Keywords - description: >- Prompts represent questions that users ask AI engines (ChatGPT, Google AI Overviews). Analyzing a prompt reveals which sources and brands are cited in AI responses, and produces GEO recommendations to improve your content's visibility in AI-generated answers. name: Prompts - description: >- Brand Voices encode your editorial identity for AI-generated content. When configured, Atomic Content and AI features automatically adopt your writing style, tone, and brand guidelines. Select a brand voice ID in the `settings` of `POST /v1/contents/:contentId/atomic`. name: Brand Voices - description: >- Knowledge Documents are reference materials (text, URLs, or files) that enrich AI content generation with your expertise. When knowledge sources are enabled in Atomic Content settings, the AI draws from these documents to produce more accurate, brand-aligned content. name: Knowledge Documents paths: /v1/workspaces/{workspaceId}/knowledge-documents: post: tags: - Knowledge Documents summary: Create a knowledge document description: >- Creates a knowledge document from exactly one source: text (`content`), a web page (`url`) or a file (`fileName` and `size` in bytes). The document starts in 'pending' status while it is processed. For a file, the response also carries `upload`, a presigned S3 POST form valid for 15 minutes: send a multipart POST to `upload.url` with every `upload.fields` entry first, then the file as the `file` field, which must come last. Processing starts once the file is in storage, with no further call. Files go up to 50 MB; accepted types: pdf, csv, txt, xlsx, docx. A 403 on a file means the V2 knowledge base or direct upload is not enabled for the workspace, or the user is a guest writer: only workspace owners and members manage knowledge base files. Refusals: 400 knowledge_document_upload_type_not_allowed, 400 knowledge_document_upload_too_large, 422 knowledge_document_replacement_invalid. parameters: - schema: type: string in: path name: workspaceId required: true description: Workspace ID. requestBody: required: true content: application/json: schema: type: object properties: content: description: >- Text of the document. Provide exactly one of content, url, or fileName with size. type: string minLength: 1 fileName: description: >- Original file name, extension included. Give it with size to create a file document. type: string minLength: 1 maxLength: 255 knowledgeFolderId: description: >- Folder that will hold the document. Omit it to file the document in General. type: string name: type: string minLength: 1 description: Display name of the document. replaces: description: >- IDs of existing knowledge documents this one replaces. The new document does not inherit the replaced document's folder: pass its knowledgeFolderId to keep it there. maxItems: 500 type: array items: type: string size: description: File size in bytes, up to 50 MB. Give it with fileName. type: integer minimum: 0 exclusiveMinimum: true url: description: >- Web page to index. Provide exactly one of content, url, or fileName with size. type: string format: uri required: - name additionalProperties: false responses: '201': description: Default Response content: application/json: schema: type: object properties: contentType: nullable: true description: >- MIME type of the uploaded file. Null when the document has no file. type: string createdAt: type: string description: ISO 8601 creation date. createdById: nullable: true description: ID of the user who created the document. type: string failureReason: nullable: true description: Why processing failed. Null unless the status is failed. type: string enum: - upload_expired - unsupported_type - encrypted - page_too_large - too_large - optimization_timeout - processing_error - kb_failed fileName: nullable: true description: Original file name. Null when the document has no file. type: string fileSize: nullable: true description: File size in bytes. Null when the document has no file. type: integer id: type: string description: Unique identifier of the knowledge document. knowledgeFolderId: nullable: true description: >- Knowledge folder holding the document. Null for the General folder and for page documents. type: string name: type: string description: Name of the document. nbCitations: nullable: true description: >- Number of times AI content cited this document. Null for a document created before citations were counted and never cited since. type: integer pageId: nullable: true description: >- Page the document is attached to. Null for workspace documents. type: string reviewStatus: nullable: true description: >- to_validate when the document is 18 months old or more and was not validated in the last 3 months, up_to_date otherwise. Null until processing has succeeded. type: string enum: - to_validate - up_to_date status: nullable: true description: Processing status. type: string enum: - pending - success - failed summary: nullable: true description: Summary of the document content. type: string type: nullable: true description: Document type. type: string enum: - text - url - file updatedAt: nullable: true description: ISO 8601 date of the last update. type: string updatedById: nullable: true description: ID of the user who last updated the document. type: string url: nullable: true description: >- Source URL of a url document. Known on the single-document routes only, null elsewhere. type: string validatedAt: nullable: true description: ISO 8601 date of the last validation. type: string validatedById: nullable: true description: ID of the user who last validated the document. type: string workspace: type: object properties: id: type: string name: type: string websiteUrl: type: string required: - id - name - websiteUrl additionalProperties: false description: Workspace this knowledge document belongs to. upload: description: >- Presigned S3 POST form, present only for a file document. Valid for 15 minutes. type: object properties: fields: type: object additionalProperties: type: string description: >- Form fields to send first, in this order, before the file. url: type: string description: URL to POST the multipart form to. required: - fields - url additionalProperties: false required: - contentType - createdAt - createdById - failureReason - fileName - fileSize - id - knowledgeFolderId - name - nbCitations - pageId - reviewStatus - status - summary - type - updatedAt - updatedById - url - validatedAt - validatedById - workspace additionalProperties: false components: securitySchemes: apiKey: bearerFormat: API Key description: API key starting with `sk_`. Generate one in **Settings > API Keys**. scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.