> ## Documentation Index
> Fetch the complete documentation index at: https://help.gorelo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Creates a document.

> The document goes last among the documents that share its parent. Under a parent it takes
the parent's client; the parent has to exist and not be archived.
            
`Body` must not embed images as `data:` URLs: upload each image with
`POST /v1/attachments` and use the url it returns. Links in the body to other
documents, devices, custom assets, contacts, passwords and structured documents are added
to the document's related items, as the app adds them.
            
Attach files after creating, with `PATCH /v1/documents/{documentId}`.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/documents
openapi: 3.0.4
info:
  title: Public API
  description: Gorelo Public API documentation.
  version: 1.0.0
servers:
  - url: https://api.usw.gorelo.io
    description: US
  - url: https://api.aue.gorelo.io
    description: Australia
security:
  - ApiKeyAuth: []
tags:
  - name: Attachments
    description: "Uploading a file, for anything that can carry one. One endpoint rather than one per record\r\ntype, because the upload itself is identical - only the record it is checked against differs."
  - name: Alerts
    description: Alerts management operations
  - name: Assets
    description: Assets management operations
  - name: Billing
    description: Billing management operations
  - name: Tickets
    description: Tickets management operations
  - name: Clients
    description: Clients management operations
  - name: Contacts
    description: Contacts management operations
  - name: Deletions
    description: Deletions management operations
  - name: Documents
    description: Documents management operations
  - name: Forms
    description: Forms management operations
  - name: Organization
    description: Organization management operations
  - name: Projects
    description: Projects management operations
paths:
  /v1/documents:
    post:
      tags:
        - Documents
      summary: Creates a document.
      description: "The document goes last among the documents that share its parent. Under a parent it takes\r\nthe parent's client; the parent has to exist and not be archived.\r\n            \r\n`Body` must not embed images as `data:` URLs: upload each image with\r\n`POST /v1/attachments` and use the url it returns. Links in the body to other\r\ndocuments, devices, custom assets, contacts, passwords and structured documents are added\r\nto the document's related items, as the app adds them.\r\n            \r\nAttach files after creating, with `PATCH /v1/documents/{documentId}`."
      operationId: post_v1_documents
      requestBody:
        description: The document.
        content:
          application/json-patch+json:
            schema:
              $ref: '#/components/schemas/CreateDocumentCommand'
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDocumentCommand'
          text/json:
            schema:
              $ref: '#/components/schemas/CreateDocumentCommand'
          application/*+json:
            schema:
              $ref: '#/components/schemas/CreateDocumentCommand'
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/DocumentDetailModelBaseResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentDetailModelBaseResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/DocumentDetailModelBaseResponse'
        '400':
          description: Bad Request
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ObjectBaseResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectBaseResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/ObjectBaseResponse'
        '401':
          description: Unauthorized
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ObjectBaseResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectBaseResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/ObjectBaseResponse'
        '500':
          description: Internal Server Error
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ObjectBaseResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectBaseResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/ObjectBaseResponse'
components:
  schemas:
    CreateDocumentCommand:
      type: object
      properties:
        Title:
          type: string
          description: Title. Required, max 200 characters.
          nullable: true
        Body:
          type: string
          description: >-
            The body, as HTML. Must not embed images as `data:` URLs - upload
            them first.
          nullable: true
        ParentDocumentId:
          type: string
          description: >-
            The document to nest this one under; omit or null for a top-level
            document.
          format: uuid
          nullable: true
        ClientId:
          type: integer
          description: "The client the document belongs to; omit or null for an internal document. Under a parent\r\nthe document takes the parent's client, and a different value here is rejected."
          format: int64
          nullable: true
      additionalProperties: false
      description: A new document.
    DocumentDetailModelBaseResponse:
      type: object
      properties:
        StatusCode:
          $ref: '#/components/schemas/HttpStatusCode'
        IsSuccess:
          type: boolean
        Data:
          $ref: '#/components/schemas/DocumentDetailModel'
        DataContext:
          type: object
          additionalProperties: false
          nullable: true
          example: null
        Notifications:
          type: array
          items:
            $ref: '#/components/schemas/Error'
      additionalProperties: false
    ObjectBaseResponse:
      type: object
      properties:
        StatusCode:
          $ref: '#/components/schemas/HttpStatusCode'
        IsSuccess:
          type: boolean
        Data:
          nullable: true
        DataContext:
          $ref: '#/components/schemas/ErrorDataContext'
        Notifications:
          type: array
          items:
            $ref: '#/components/schemas/Error'
      additionalProperties: false
    HttpStatusCode:
      enum:
        - 100
        - 101
        - 102
        - 103
        - 200
        - 201
        - 202
        - 203
        - 204
        - 205
        - 206
        - 207
        - 208
        - 226
        - 300
        - 301
        - 302
        - 303
        - 304
        - 305
        - 306
        - 307
        - 308
        - 400
        - 401
        - 402
        - 403
        - 404
        - 405
        - 406
        - 407
        - 408
        - 409
        - 410
        - 411
        - 412
        - 413
        - 414
        - 415
        - 416
        - 417
        - 421
        - 422
        - 423
        - 424
        - 426
        - 428
        - 429
        - 431
        - 451
        - 500
        - 501
        - 502
        - 503
        - 504
        - 505
        - 506
        - 507
        - 508
        - 510
        - 511
      type: integer
      format: int32
    DocumentDetailModel:
      type: object
      properties:
        Id:
          type: string
          description: Document identifier.
          format: uuid
        Title:
          type: string
          description: Title.
        Body:
          type: string
          description: >-
            The body of the current version, as HTML. Image links carry a
            time-limited access token.
        ParentDocumentId:
          type: string
          description: >-
            The document this one is nested under; null for a top-level
            document.
          format: uuid
          nullable: true
        RootDocumentId:
          type: string
          description: >-
            The top-level document of this document's tree; its own id when it
            is top level.
          format: uuid
        Depth:
          type: integer
          description: >-
            How deep the document is nested: 0 for a top-level document, 1 for
            its children, and so on.
          format: int32
        ChildCount:
          type: integer
          description: >-
            Number of documents nested directly under this one, archived ones
            included.
          format: int32
        DocumentOrder:
          type: integer
          description: >-
            Position among the documents that share its parent, lowest first.
            Read-only.
          format: int32
        Children:
          type: array
          items:
            $ref: '#/components/schemas/DocumentChildModel'
          description: >-
            The documents nested directly under this one, in their display
            order.
        ClientId:
          type: integer
          description: The client the document belongs to; null for an internal document.
          format: int64
          nullable: true
        IsStarred:
          type: boolean
          description: >-
            Whether the document is starred. A star is shared by everyone in the
            account, not kept per user.
        PublicLinkEnabled:
          type: boolean
          description: Whether the document can be read by anyone holding its public link.
        PublicLinkUrl:
          type: string
          description: "The public link to the current version, in the form the app copies to the clipboard. Null\r\nwhile `PublicLinkEnabled` is false."
          nullable: true
        PublishToPortalEnabled:
          type: boolean
          description: Whether the document is published to the client portal.
        AlternateName:
          type: string
          description: >-
            The name the document is shown under in the client portal; null when
            none is set.
          nullable: true
        Status:
          $ref: '#/components/schemas/CodeModel'
        Attachments:
          type: array
          items:
            $ref: '#/components/schemas/CommentAttachmentModel'
          description: "Files attached to the current version. Each url carries a time-limited access token; do\r\nnot store it."
        RelatedItems:
          type: array
          items:
            $ref: '#/components/schemas/DocumentRelatedItemModel'
          description: The records this document is linked to.
        CreatedOn:
          type: string
          description: When the document was created (UTC).
          format: date-time
        CreatedById:
          type: integer
          description: >-
            Technician who created the document; 0 when it was created through
            the API.
          format: int64
        UpdatedOn:
          type: string
          description: >-
            When the document was last changed (UTC); its creation time if it
            has not been changed since.
          format: date-time
          nullable: true
        UpdatedById:
          type: integer
          description: >-
            Technician who last changed the document, or who created it if it
            has not been changed since; 0 when that came through the API.
          format: int64
          nullable: true
      additionalProperties: false
      description: >-
        A single document, with its body, children, attachments and related
        items.
    Error:
      type: object
      properties:
        Code:
          pattern: ^[0-9]{6}$
          type: string
          description: 6-digit MMTTNN error code. See the Public API error-code registry.
          example: '070101'
        Message:
          type: string
        PropertyName:
          type: string
          nullable: true
        ActionHint:
          type: string
          nullable: true
        DocUrl:
          type: string
          nullable: true
      additionalProperties: false
    ErrorDataContext:
      type: object
      properties:
        TraceId:
          type: string
          description: Request correlation id. Quote this when reporting a problem.
          nullable: true
      additionalProperties: false
      description: "The `DataContext` of an error response: carries the correlation id for the failed\r\nrequest."
    DocumentChildModel:
      type: object
      properties:
        Id:
          type: string
          description: Document identifier.
          format: uuid
        Title:
          type: string
          description: Title.
        ChildCount:
          type: integer
          description: Number of documents nested directly under this one.
          format: int32
      additionalProperties: false
      description: A document nested directly under another.
    CodeModel:
      type: object
      properties:
        Id:
          type: integer
          description: >-
            Numeric identifier of the coded value (e.g. status, priority, type,
            or source id).
          format: int64
          example: 1
        Name:
          type: string
          description: Display name of the coded value.
      additionalProperties: false
      description: >-
        A coded value, such as a status, priority, type or source, as an id and
        a display name.
    CommentAttachmentModel:
      type: object
      properties:
        Name:
          type: string
          description: File name.
        Url:
          type: string
          description: Temporary secure download link. Expires.
      additionalProperties: false
      description: A file attached to a comment, and what the upload endpoint returns.
    DocumentRelatedItemModel:
      type: object
      properties:
        Id:
          type: integer
          description: Identifier of the link itself - what the remove endpoint takes.
          format: int64
        ItemId:
          type: string
          description: >-
            Identifier of the linked record, as text: a Guid for documents,
            custom assets and agent assets, a number for contacts.
        ItemType:
          $ref: '#/components/schemas/CodeModel'
      additionalProperties: false
      description: A link between a document and another record.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      description: >-
        Your Gorelo API key. See [Generate API key](/generate-api-key). If your
        data is hosted in Australia, click the base URL at the top of this page
        and select `https://api.aue.gorelo.io`.
      name: X-API-Key
      in: header

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.