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

# Create an org- or repo-tier blueprint

> Create a blueprint.  ``type`` is inferred from ``repo_name``.

``source`` defaults to ``database``.  With ``source='git'`` the YAML
(and any ``includes``) is read from ``.devin/blueprint.yaml`` on the
repo's default branch — 404 when the file is absent, 422 when it is
invalid, 502 when the git provider is unreachable.

Per spec, this never auto-triggers a build — callers must
``POST /builds`` explicitly.

## Permissions

Requires a [service user](/api-reference/v3/service-users/members-service-users) or [personal access token](/api-reference/personal-access-tokens) with the `ManageRepoBlueprints` permission at the organization level. Creating org-tier blueprints requires the `ManageOrgSnapshots` permission.

## Behavior

Creates an org- or repo-tier blueprint. A blueprint defines the declarative environment configuration for Devin sessions. Mutating a blueprint does not auto-trigger a build — you must explicitly call the builds endpoint.

<Note>
  Blueprints do not exist independently of your environment configuration. Creating a blueprint with a `repo_name` **also adds that repository to the environment** — there is no separate endpoint to register the repo first. The repository is cloned into the environment on the next build, and indexing is kicked off for it.

  The reverse holds too: removing a repository from the environment (the **Include in environment** toggle in the UI) deletes every blueprint for that repo, including all of its workspace scopes.
</Note>

The repository name must be one Devin can already access through your Git integration (for example `owner/repo`); an unknown or inaccessible repo returns `404` and no blueprint is created. If an active blueprint already exists for that repo and scope, the request returns `409` — use the update endpoint instead.


## OpenAPI

````yaml v3-openapi.yaml POST /v3/organizations/{org_id}/snapshot-setup/blueprints
openapi: 3.1.0
info:
  description: Devin v3 API with Service User authentication and RBAC
  title: Devin API v3
  version: 3.0.0
servers: []
security:
  - bearerAuth: []
paths:
  /v3/organizations/{org_id}/snapshot-setup/blueprints:
    post:
      tags:
        - snapshot_setup
      summary: Create an org- or repo-tier blueprint
      description: |-
        Create a blueprint.  ``type`` is inferred from ``repo_name``.

        ``source`` defaults to ``database``.  With ``source='git'`` the YAML
        (and any ``includes``) is read from ``.devin/blueprint.yaml`` on the
        repo's default branch — 404 when the file is absent, 422 when it is
        invalid, 502 when the git provider is unreachable.

        Per spec, this never auto-triggers a build — callers must
        ``POST /builds`` explicitly.
      operationId: >-
        create_org_blueprint_v3_organizations__org_id__snapshot_setup_blueprints_post
      parameters:
        - description: 'Organization ID (prefix: org-)'
          in: path
          name: org_id
          required: true
          schema:
            example: org-abc123def456
            title: Org Id
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrgBlueprintBody'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Blueprint'
          description: Successful Response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
          description: Not Found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
          description: Conflict
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
          description: Unprocessable Content
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
          description: Too Many Requests
components:
  schemas:
    CreateOrgBlueprintBody:
      properties:
        contents:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Optional initial YAML body for the blueprint. Not allowed with
            source='git' (contents come from the repo).
          title: Contents
        repo_name:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            If set, creates a repo-tier blueprint for that repository. If
            omitted, creates an org-wide (org-tier) blueprint.
          title: Repo Name
        source:
          anyOf:
            - enum:
                - git
                - database
              type: string
            - type: 'null'
          description: >-
            Repo-tier only. 'git' reads .devin/blueprint.yaml (and its includes)
            from the repo's default branch and keeps the blueprint in sync with
            it; 'database' stores the YAML in Devin. Defaults to 'database' when
            omitted.
          title: Source
      title: CreateOrgBlueprintBody
      type: object
    Blueprint:
      description: |-
        Public ``Blueprint`` resource shape.

        Note: the ``type`` enum may grow in the future; clients MUST gracefully
        handle unknown values.  YAML contents are fetched separately via
        ``GET /blueprints/{id}/contents``.
      properties:
        blueprint_id:
          title: Blueprint Id
          type: string
        build_on_default_branch_commit:
          anyOf:
            - type: boolean
            - type: 'null'
          description: >-
            Whether each push to the repo's default branch builds the
            environment. Null unless this is a repo's root blueprint.
          title: Build On Default Branch Commit
        created_at:
          title: Created At
          type: integer
        repo_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Repo Name
        report_check_runs:
          anyOf:
            - type: boolean
            - type: 'null'
          description: >-
            Whether each commit build is reported as a GitHub check run on the
            commit. Null unless this is a repo's root blueprint.
          title: Report Check Runs
        source:
          anyOf:
            - enum:
                - git
                - database
              type: string
            - type: 'null'
          description: >-
            Where the YAML is authored: 'git' (synced from .devin/blueprint.yaml
            in the repo) or 'database' (edited via the API/UI). Always null for
            enterprise- and org-tier blueprints.
          title: Source
        type:
          enum:
            - enterprise
            - org
            - repo
          title: Type
          type: string
        updated_at:
          title: Updated At
          type: integer
      required:
        - blueprint_id
        - type
        - repo_name
        - created_at
        - updated_at
      title: Blueprint
      type: object
    ProblemDetail:
      description: >-
        RFC 9457 application/problem+json error body for the v3 API.


        detail is retained from the legacy {"detail": ...} body for back-compat;
        the

        other members are additive. errors carries field-level validation
        failures

        (422 only).
      properties:
        detail:
          anyOf:
            - type: string
            - type: 'null'
          description: A human-readable explanation specific to this occurrence.
          title: Detail
        error_code:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Machine-readable code for blocked-action refusals (e.g.
            "user_frozen", "migrated_session").
          title: Error Code
        errors:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          description: Field-level validation errors (422 responses only).
          title: Errors
        instance:
          anyOf:
            - type: string
            - type: 'null'
          description: A URI reference (the request path) for this occurrence.
          title: Instance
        status:
          description: The HTTP status code.
          title: Status
          type: integer
        title:
          description: A short, human-readable summary of the problem type.
          title: Title
          type: string
        type:
          default: about:blank
          description: A URI reference identifying the problem type.
          title: Type
          type: string
      required:
        - title
        - status
      title: ProblemDetail
      type: object
  securitySchemes:
    bearerAuth:
      description: 'Service User credential (prefix: cog_)'
      scheme: bearer
      type: http

````

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