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

# Create brief

> Creates a brief from a link or an uploaded PDF. Requires permission `add/brief`. Send the body as `multipart/form-data`, also for a link brief.

**Error codes** (`failedCode`):
`brief-001` required field missing · `brief-002` name already used by another brief · `brief-007` url is not a valid `https://` URL · `brief-009` over a limit (name 100, url 2048 characters) · `brief-011` `roleIds` is not an array · `brief-015` file is not a PDF or is larger than 20 MB · `brief-017` invalid `type` or `sourceType` · `brief-033` brief or role not found · `brief-036` the file could not be stored (500, nothing is saved).



## OpenAPI

````yaml /openapi/public/openapi-flow.json post /brief
openapi: 3.0.0
info:
  title: API - Flow
  version: 3.0.0
  description: API Documentation - RESTful API for field operations management.
servers:
  - url: https://apiweb.mile.app/api/v3
security:
  - bearerAuth: []
tags:
  - name: Flow
    description: >-
      Flow is the mobile field application workflow, setting it correctly is
      critical to the success of the field workers in doing their job
      efficiently. Flow attributes consist of IDs, pages, components,
      configurations, and time. The Flow will be used at Task, Automation, or
      Schedule.


      **To see the details of flow object, please follow [this
      link](#tag/flow_model)**
  - name: Automation
    description: >-
      Automation enables you to set up automation based on tasks' events and
      data source's events. It might help you automate creation of tasks, task
      assignment, task placement, task webhook, data source update, datasource
      creation, and data source webhook. Automation attributes consist of IDs,
      automation name, automation type, automation details, and rules.


      **To see the details of automation object, please follow [this
      link](#tag/automation_model)**
  - name: Order Type
    description: >-
      An order type is the blueprint for orders: the list of steps, which flow
      each step uses, and how an order moves from one step to the next. Order
      types are versioned: you edit a draft, validate or simulate it, then
      publish it. These endpoints are served under `/api/v4`.
  - name: Brief
    description: >-
      A brief is a reference PDF, such as an SOP, a product guide or a campaign
      brief, that your field team reads in the mobile app. It comes from an
      https link or an uploaded PDF, and it is shared with chosen roles or with
      every role. These endpoints are served under `/api/v4`.
paths:
  /brief:
    servers:
      - url: https://apiweb.mile.app/api/v4
    post:
      tags:
        - Brief
      summary: Create brief
      description: >-
        Creates a brief from a link or an uploaded PDF. Requires permission
        `add/brief`. Send the body as `multipart/form-data`, also for a link
        brief.


        **Error codes** (`failedCode`):

        `brief-001` required field missing · `brief-002` name already used by
        another brief · `brief-007` url is not a valid `https://` URL ·
        `brief-009` over a limit (name 100, url 2048 characters) · `brief-011`
        `roleIds` is not an array · `brief-015` file is not a PDF or is larger
        than 20 MB · `brief-017` invalid `type` or `sourceType` · `brief-033`
        brief or role not found · `brief-036` the file could not be stored (500,
        nothing is saved).
      operationId: createBrief
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                name:
                  description: >-
                    Brief name, max 100 characters, unique in your organization
                    (briefs in Trash do not count).

                    **Example**: `SOP Servis Berkala 10.000 km`
                  type: string
                type:
                  description: Document type. Only `pdf` today.
                  type: string
                  enum:
                    - pdf
                sourceType:
                  description: >-
                    `link`: the brief points to a URL. `upload`: the brief holds
                    an uploaded PDF.
                  type: string
                  enum:
                    - link
                    - upload
                url:
                  description: >-
                    Required when `sourceType` is `link`. Must start with
                    `https://`, max 2048 characters. Ignored for `upload`.

                    **Example**: `https://docs.example.com/oli-mesin-2026.pdf`
                  type: string
                file:
                  description: >-
                    The PDF, max 20 MB. Required when `sourceType` is `upload`.
                    `fileName` and `fileSize` are read from this file; do not
                    send them.
                  type: string
                  format: binary
                roleIds[]:
                  description: >-
                    Role IDs that can see the brief, one field per role. Leave
                    it out to show the brief to every role.

                    **Example**: `64b0c1d2e3f4a5b6c7d8e9f0`
                  type: array
                  items:
                    type: string
              required:
                - name
                - type
                - sourceType
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                    description: Status of response.
                  message:
                    description: Message of API response.
                    type: string
                  data:
                    description: The created brief.
                    type: object
                    additionalProperties: true
                example:
                  status: true
                  message: Success.
                  data:
                    _id: 6738a1f2c4e9b10012ab34cd
                    name: SOP Servis Berkala 10.000 km
                    type: string
                    sourceType: upload
                    url: >-
                      https://storage.example.com/production/5f1a2b3c4d5e6f7081920a1b/brief/2026/11/16/1763270400_sop-servis-berkala.pdf
                    fileName: sop-servis-berkala.pdf
                    fileSize: 2483112
                    roleIds:
                      - 64b0c1d2e3f4a5b6c7d8e9f0
                      - 64b0c1d2e3f4a5b6c7d8e9f1
                    roles:
                      - _id: 64b0c1d2e3f4a5b6c7d8e9f0
                        name: Mekanik
                      - _id: 64b0c1d2e3f4a5b6c7d8e9f1
                        name: Service Advisor
                    createdBy: admin@artaboga.example
                    updatedBy: admin@artaboga.example
                    createdTime: '2026-11-16T03:20:00.000000Z'
                    updatedTime: '2026-11-16T03:20:00.000000Z'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                    description: Status of response.
                  message:
                    description: Message of API response.
                    type: string
                  data:
                    description: Always null on error.
                    type: object
                    additionalProperties: true
                  failedCode:
                    description: Error code, see the descriptions above.
                    type: string
                example:
                  status: false
                  message: The name has already been taken.
                  data: null
                  failedCode: brief-002
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                    description: Status of response.
                  message:
                    description: Message of API response.
                    type: string
                  data:
                    description: Always null on error.
                    type: object
                    additionalProperties: true
                  failedCode:
                    description: Error code, see the descriptions above.
                    type: string
                example:
                  status: false
                  message: The file could not be stored.
                  data: null
                  failedCode: brief-036
      deprecated: false
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Use a valid Bearer token to authenticate.

````

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