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

# Start connecting a Google Calendar

> Returns a URL to open in a browser. Google has no credential a request body can carry, so connecting one is two steps: ask for this URL, let the customer consent, and Roark finishes the rest server-side (it exchanges the code, verifies that both calendar permissions were granted, reads the account’s own timezone when none was given, and stores the connection). Nothing is created until the customer consents, and a link that is not used expires. Read the result with `GET /v1/connections/calendar?provider=GOOGLE`.



## OpenAPI

````yaml /api-reference/openapi.documented.json post /v1/connections/calendar/google/authorize-url
openapi: 3.1.0
info:
  title: Roark Analytics API
  description: >-
    The Roark Analytics API gives you access to the same API that powers the
    award winning Roark Analytics platform.
  version: 1.0.0
servers:
  - description: Production
    url: https://api.roark.ai
security:
  - Bearer: []
tags:
  - name: Health
    x-displayName: Health
  - name: Authentication
    x-displayName: Current credential
  - name: Project API Key
    x-displayName: Project API keys
  - name: Personal API Key
    x-displayName: Personal API keys
  - name: Agent
    x-displayName: Agents
  - name: Agent Endpoint
    x-displayName: Endpoints
  - name: Tool
    x-displayName: Tools
  - name: Agent Setup
    x-displayName: Automatic test setup
  - name: Autoimprove
    x-displayName: Autoimprove
  - name: Customer Flow
    x-displayName: Customer flows
  - name: Simulation Persona
    x-displayName: Personas
  - name: Simulation Environment
    x-displayName: Environments
  - name: Simulation Template
    x-displayName: Templates
  - name: Simulation Run Plan
    x-displayName: Plans
  - name: Simulation Run
    x-displayName: Runs
  - name: Simulation Tool Mock
    x-displayName: Tool mocks and fixtures
  - name: Metric
    x-displayName: Definitions
  - name: Metric Variant
    x-displayName: Variants
  - name: Metric Policy
    x-displayName: Policies
  - name: Metric Collection Job
    x-displayName: Collection jobs
  - name: Call
    x-displayName: Calls
  - name: Chat
    x-displayName: Chats
  - name: Customer
    x-displayName: Customers
  - name: Issue
    x-displayName: Issues
  - name: Analytics
    x-displayName: Analytics
  - name: Dashboard
    x-displayName: Dashboards
  - name: Live Report
    x-displayName: Reports
  - name: Agent Connection
    x-displayName: Agent platforms
  - name: Calendar Connection
    x-displayName: Calendars
  - name: MCP Server Connection
    x-displayName: MCP servers
  - name: Knowledge Base
    x-displayName: Knowledge bases
  - name: HTTP Request Definition
    x-displayName: HTTP request definitions
  - name: Webhook
    x-displayName: Webhooks
  - name: Config
    x-displayName: Config as code
  - name: Organization Project
    x-displayName: Projects
  - name: Organization Project Member
    x-displayName: Project members
  - name: Usage
    x-displayName: Usage
  - name: Benchmark
    x-displayName: Benchmarks
paths:
  /v1/connections/calendar/google/authorize-url:
    post:
      tags:
        - Calendar Connection
      summary: Start connecting a Google Calendar
      description: >-
        Returns a URL to open in a browser. Google has no credential a request
        body can carry, so connecting one is two steps: ask for this URL, let
        the customer consent, and Roark finishes the rest server-side (it
        exchanges the code, verifies that both calendar permissions were
        granted, reads the account’s own timezone when none was given, and
        stores the connection). Nothing is created until the customer consents,
        and a link that is not used expires. Read the result with `GET
        /v1/connections/calendar?provider=GOOGLE`.
      operationId: postV1ConnectionsCalendarGoogleAuthorize-url
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                calendarConnectionId:
                  type:
                    - string
                    - 'null'
                  format: uuid
                  description: >-
                    Reconnect an existing connection instead of creating one:
                    the consent screen replaces that connection’s credential in
                    place, so every tool bound to it keeps working. Use this
                    when a connection reports `INVALID_CREDENTIALS`. The
                    connection’s existing name and timezone are kept, so `label`
                    is ignored when this is set.
                label:
                  type:
                    - string
                    - 'null'
                  minLength: 1
                  maxLength: 120
                  description: >-
                    Customer-facing name for the connection, unique within the
                    project. Required unless `calendarConnectionId` is set, and
                    decided now because the consent screen has nowhere to carry
                    it.
                timezone:
                  type:
                    - string
                    - 'null'
                  minLength: 1
                  description: >-
                    The named IANA timezone to offer slots in, for example
                    `America/Los_Angeles`. Omit to adopt the Google account’s
                    own. A fixed offset such as `-08:00` is rejected: it does
                    not observe DST.
                loginHint:
                  type:
                    - string
                    - 'null'
                  format: email
                  description: >-
                    The Google account to preselect on the consent screen. A
                    hint only: it is ignored if the user is signed into another
                    account, and nothing is authorized by it.
              title: StartCalendarOauthInput
              description: Input for starting a Google Calendar connection.
      responses:
        '200':
          description: A URL to open, and when it stops working.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      authorizeUrl:
                        type: string
                        description: >-
                          Open this in a browser. After the customer consents,
                          the provider returns to Roark, which exchanges the
                          code, verifies the credential and stores the
                          connection. Read the result with `GET
                          /v1/connections/calendar?provider=…`.
                      state:
                        type: string
                        description: >-
                          The opaque single-use value this flow is identified
                          by, echoed so a caller can correlate its own UI. Not a
                          credential and not accepted anywhere as one.
                      expiresAt:
                        type: string
                        description: >-
                          When the link stops working, ISO 8601. Start again
                          after that.
                    required:
                      - authorizeUrl
                      - state
                      - expiresAt
                    title: CalendarOauthStart
                required:
                  - data
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Validation error
              example:
                type: validation
                code: invalid_parameter
                message: The request was invalid
                param: email
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Authentication error
              example:
                type: authentication
                code: unauthorized
                message: Authentication required
          description: Unauthorized
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Server error
              example:
                type: internal
                code: internal_error
                message: Internal server error
          description: Internal Server Error
      x-codeSamples:
        - lang: JavaScript
          source: |-
            import Roark from '@roarkanalytics/sdk';

            const client = new Roark({
              bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted
            });

            const response = await client.calendarConnection.startGoogleOauth();

            console.log(response.data);
        - lang: Python
          source: |-
            import os
            from roark_analytics import Roark

            client = Roark(
                bearer_token=os.environ.get("ROARK_API_BEARER_TOKEN"),  # This is the default and can be omitted
            )
            response = client.calendar_connection.start_google_oauth()
            print(response.data)
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        type:
          type: string
          enum:
            - validation
            - authentication
            - forbidden
            - not_found
            - conflict
            - payment_required
            - rate_limit
            - internal
          description: The error type category
          examples:
            - validation
            - authentication
        code:
          type: string
          description: Machine-readable error code identifier
          examples:
            - invalid_parameter
            - missing_required_field
            - unauthorized
        message:
          type: string
          description: Human-readable error message
          examples:
            - The request was invalid
            - Authentication required
        param:
          type: string
          description: The parameter that caused the error (if applicable)
          examples:
            - email
            - user_id
        details:
          description: Additional error context information
      required:
        - type
        - code
        - message
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT

````

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