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

# Get Linear install URL

> Returns the linear.app URL that installs Aether's Linear app for the organization, with a state signed for the caller and the organization.

Use this tool when you need to:
- Connect a Linear workspace to an organization so its issues can start tasks in Aether
- Connect Linear again after disconnectLinear, or connect another Linear workspace in its place

Examples:
- GET /orgs/{orgID}/auth/linear/url
- GET /orgs/6f1c2a9e-3b7d-4c55-9a2e-0d8b1f4e7c21/auth/linear/url?redirect_to=aether://linear-connected

Hints:
- orgID is the organization's uuid. redirect_to is optional, at most 512 characters; the schema answers 422 for a longer value or one that does not parse as a URL. Answers 200 with url.
- Open url in a browser: the caller authorizes the app on linear.app, then Linear redirects to Aether's callback, which stores the installation with the caller as its default actor (whom its tasks are created as). The signed state expires after 15 minutes.
- After a successful connect the browser returns to redirect_to only when it is exactly aether://linear-connected or on the Aether web app's own scheme and host; otherwise, and after any failure, it lands on the web app's settings page with ?linear= naming the outcome.
- The callback installs nothing when the caller is no longer an owner or admin of the organization, the organization already holds a Linear installation, or the Linear workspace is connected to another Aether organization; this operation does not check whether Linear is already connected.
- Use getLinearStatus instead to see whether Linear is connected (disconnectLinear first to replace it), and getSlackInstallUrl or getSentryInstallUrl to connect Slack or Sentry.
- Owners and admins of the organization in the path, with a session or a platform API key: a member, viewer or billing member is refused with 403 org_role_insufficient before redirect_to is validated, a non-member with 403 org_membership_required, an orgID that is not a uuid with 400, and an agent host's grant with 403 agent_host_route_not_allowed. A deployment without a Linear app does not serve it (404).



## OpenAPI

````yaml api-reference/openapi.json GET /orgs/{orgID}/auth/linear/url
openapi: 3.1.0
info:
  title: Aether API
  version: 0.1.0
servers:
  - url: https://api.runaether.dev
security:
  - bearerAuth: []
paths:
  /orgs/{orgID}/auth/linear/url:
    get:
      tags:
        - linear
      summary: Get Linear install URL
      description: >-
        Returns the linear.app URL that installs Aether's Linear app for the
        organization, with a state signed for the caller and the organization.


        Use this tool when you need to:

        - Connect a Linear workspace to an organization so its issues can start
        tasks in Aether

        - Connect Linear again after disconnectLinear, or connect another Linear
        workspace in its place


        Examples:

        - GET /orgs/{orgID}/auth/linear/url

        - GET
        /orgs/6f1c2a9e-3b7d-4c55-9a2e-0d8b1f4e7c21/auth/linear/url?redirect_to=aether://linear-connected


        Hints:

        - orgID is the organization's uuid. redirect_to is optional, at most 512
        characters; the schema answers 422 for a longer value or one that does
        not parse as a URL. Answers 200 with url.

        - Open url in a browser: the caller authorizes the app on linear.app,
        then Linear redirects to Aether's callback, which stores the
        installation with the caller as its default actor (whom its tasks are
        created as). The signed state expires after 15 minutes.

        - After a successful connect the browser returns to redirect_to only
        when it is exactly aether://linear-connected or on the Aether web app's
        own scheme and host; otherwise, and after any failure, it lands on the
        web app's settings page with ?linear= naming the outcome.

        - The callback installs nothing when the caller is no longer an owner or
        admin of the organization, the organization already holds a Linear
        installation, or the Linear workspace is connected to another Aether
        organization; this operation does not check whether Linear is already
        connected.

        - Use getLinearStatus instead to see whether Linear is connected
        (disconnectLinear first to replace it), and getSlackInstallUrl or
        getSentryInstallUrl to connect Slack or Sentry.

        - Owners and admins of the organization in the path, with a session or a
        platform API key: a member, viewer or billing member is refused with 403
        org_role_insufficient before redirect_to is validated, a non-member with
        403 org_membership_required, an orgID that is not a uuid with 400, and
        an agent host's grant with 403 agent_host_route_not_allowed. A
        deployment without a Linear app does not serve it (404).
      operationId: getLinearInstallUrl
      parameters:
        - in: path
          name: orgID
          required: true
          schema:
            format: uuid
            type: string
        - explode: false
          in: query
          name: redirect_to
          schema:
            format: uri
            maxLength: 512
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegrationInstallURL'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LinearErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LinearErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrgAuthorizationErrorResponse'
          description: Forbidden
        '410':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LinearErrorResponse'
          description: Gone
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LinearErrorResponse'
          description: Unprocessable Entity
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LinearErrorResponse'
          description: Internal Server Error
components:
  schemas:
    IntegrationInstallURL:
      additionalProperties: false
      properties:
        url:
          format: uri
          minLength: 1
          type: string
      required:
        - url
      type: object
    LinearErrorResponse:
      additionalProperties: false
      properties:
        code:
          enum:
            - agent_profile_not_found
            - bad_gateway
            - bad_request
            - cli_upgrade_required
            - client_outdated
            - conflict
            - default_actor_not_member
            - forbidden
            - gateway_timeout
            - gone
            - internal_error
            - linear_project_not_found
            - linear_team_not_found
            - method_not_allowed
            - not_acceptable
            - not_connected
            - not_found
            - not_implemented
            - payment_required
            - precondition_failed
            - project_not_found
            - project_repo_disconnected
            - rate_limited
            - request_canceled
            - request_timeout
            - request_too_large
            - route_exists
            - route_not_found
            - service_unavailable
            - unauthenticated
            - unsupported_media_type
            - validation_failed
          minLength: 1
          type: string
        error:
          minLength: 1
          type: string
        errors:
          items:
            $ref: '#/components/schemas/ErrorDetail'
          type: array
      required:
        - error
        - code
      type: object
    OrgAuthorizationErrorResponse:
      additionalProperties: false
      properties:
        code:
          enum:
            - org_membership_required
            - org_role_insufficient
            - org_suspended
            - account_deleting
            - agent_host_route_not_allowed
            - credential_kind_not_admitted
            - grant_scope_insufficient
          type: string
        error:
          minLength: 1
          type: string
      required:
        - error
        - code
      type: object
    ErrorDetail:
      additionalProperties: false
      properties:
        location:
          description: >-
            Where the error occurred, e.g. 'body.items[3].tags' or
            'path.thing-id'
          type: string
        message:
          description: Error message text
          type: string
        value:
          description: The value at the given location
      type: object
  securitySchemes:
    bearerAuth:
      bearerFormat: JWT
      scheme: bearer
      type: http

````

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