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

> ## Agent Instructions
> Conare's API is at https://api.conare.ai. Authenticate with `Authorization: Bearer $CONARE_API_KEY`.
> The full OpenAPI spec is at https://api.conare.ai/openapi.yaml; each endpoint has a page under /api-reference, and appending .md to any page URL returns its Markdown.
> Embed with model conare-embed-1; send input_type "query" for search queries. Rerank with conare-rerank-1.
> Prefer the TypeScript SDK (`npm install conare`) or plain HTTP in examples.
> Install the Conare skill with `npx skills add https://docs.conare.ai`; search these docs over MCP at https://docs.conare.ai/mcp; the whole site is at https://docs.conare.ai/llms-full.txt.

# Sync a source now

> Starts a sync within seconds; a source already `syncing` goes on, one still `connecting` is 409.

- A Google Cloud Storage source answers 202 with its sync run (409 `run_active` while one is queued or running).
- `{"full": true}` re-reads everything (Gmail, Twenty, Granola and GitHub only); a Gmail full re-sync is billed like a first sync.




## OpenAPI

````yaml /openapi.yaml post /sources/{id}/sync
openapi: 3.1.0
info:
  title: Conare API
  version: '1'
  summary: Store your data, keep it in sync, and return the right context to your AI.
  description: >
    Write documents into namespaces, search them, and sync apps into them.


    - Base URL `https://api.conare.ai`; send `Authorization: Bearer sk-conare-…`
    (keys at conare.ai/dashboard/keys).

    - A multi-organization key sends `X-Conare-Org: <organization id>` on every
    request (`GET /organizations` lists them).

    - Bodies are JSON in snake_case; an unknown field is 400 `invalid_json`
    (`/v1` and `/v2` ignore it). Errors are `{"error": {"code", "message",
    "request_id"}}`.

    - Send every write with an `Idempotency-Key` and retry with the same key: a
    repeat within 24 hours replays the first answer.

    - 429 and 503 carry `Retry-After` (seconds).

    - `Conare-Degraded` marks a success that skipped or slowed part of search,
    e.g. `rerank` or `embed-busy`.
  contact:
    name: Conare
    url: https://conare.ai
servers:
  - url: https://api.conare.ai
security:
  - apiKey: []
tags:
  - name: Namespaces
    description: >-
      A namespace is a named set of documents, e.g. `docs` or `user-42`; the
      first write creates it.
  - name: Documents
    description: >-
      A document is `{ id, text, metadata }`, chunked and embedded on write;
      writing the same id replaces it.
  - name: Query
    description: >-
      Hybrid search (vector and keyword) over your namespaces, filtered by
      metadata and reranked.
  - name: Models
    description: >-
      Embed and rerank text with Conare's models, through Conare's own routes or
      OpenAI- and Cohere-compatible ones.
  - name: Sources
    description: Apps, buckets and custom sources, each kept in sync into one namespace.
  - name: Custom sources
    description: >-
      Documents you push from your own system, keyed by your `external_id`, with
      snapshot runs to mirror a whole set.
  - name: Parse
    description: Parse a file to Markdown without storing it.
  - name: Files
    description: >-
      Upload a file and Conare stores it as one document, each hit citing its
      page, slide, sheet rows or section.
  - name: Users
    description: >-
      Delete everything Conare holds of one of your users, across every
      namespace and source.
  - name: Events
    description: What changed, in order (`seq`), to read from a cursor.
  - name: Health
    description: Service health.
  - name: Organizations
    description: The organizations a key acts for.
paths:
  /sources/{id}/sync:
    parameters:
      - $ref: '#/components/parameters/SourceId'
    post:
      tags:
        - Sources
      summary: Sync a source now
      description: >
        Starts a sync within seconds; a source already `syncing` goes on, one
        still `connecting` is 409.


        - A Google Cloud Storage source answers 202 with its sync run (409
        `run_active` while one is queued or running).

        - `{"full": true}` re-reads everything (Gmail, Twenty, Granola and
        GitHub only); a Gmail full re-sync is billed like a first sync.
      operationId: syncSource
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                full:
                  type: boolean
                  default: false
                  description: Re-read everything the app holds, not only what changed.
      responses:
        '200':
          description: >-
            The source, due to sync now; after `{"full": true}` it also holds
            `resync`.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Source'
                  - type: object
                    properties:
                      resync:
                        type: object
                        required:
                          - full
                          - message
                        properties:
                          full:
                            type: boolean
                          message:
                            type: string
                            description: >-
                              That the sync re-reads everything, and whether its
                              rows are billed.
        '202':
          description: A Google Cloud Storage source's sync, queued.
          content:
            application/json:
              schema:
                type: object
                required:
                  - run
                properties:
                  run:
                    $ref: '#/components/schemas/Run'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '409':
          description: >-
            `conflict`: the source is still connecting, or a full re-sync was
            asked while it syncs. `run_active`: a bucket sync is queued or
            running.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          $ref: '#/components/responses/Error'
        '503':
          $ref: '#/components/responses/Error'
components:
  parameters:
    SourceId:
      name: id
      in: path
      required: true
      description: The source id, `src_…`.
      schema:
        type: string
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: >-
        One key (a UUID) per logical write, sent again on each retry: a repeat
        within 24 hours replays the first successful answer.
      schema:
        type: string
        minLength: 1
        maxLength: 255
        pattern: ^[\x21-\x7e]+$
      example: 3f2c9a0e-6a1b-4f7e-9c55-0b8f1d2e7a41
  schemas:
    Source:
      type: object
      required:
        - id
        - type
        - name
        - namespace
        - status
        - error
        - documents
        - last_synced_at
        - created_at
        - sync_interval_s
        - sync_interval_auto
        - next_sync_at
        - cost
      properties:
        id:
          type: string
          examples:
            - src_2b9c1f
        type:
          type: string
          examples:
            - hubspot
        name:
          type: string
          examples:
            - HubSpot
        namespace:
          $ref: '#/components/schemas/NamespaceName'
        status:
          type: string
          enum:
            - connecting
            - syncing
            - ready
            - error
          description: >-
            `connecting` (waiting for sign-in), `syncing`, `ready`, or `error`
            (see `error`).
        error:
          type:
            - string
            - 'null'
        documents:
          type: integer
          description: Documents synced from this source.
        last_synced_at:
          type:
            - string
            - 'null'
          format: date-time
        created_at:
          type: string
          format: date-time
        progress:
          type: object
          description: 'Only while `syncing`: the run in flight.'
          required:
            - records_pulled
          properties:
            records_pulled:
              type: integer
              description: Records read from the app so far in this run.
        sync_interval_s:
          type:
            - integer
            - 'null'
          description: >-
            Seconds between syncs in force; null while automatic and before the
            first sync.
        sync_interval_auto:
          type: boolean
          description: True when Conare picks the interval from what each sync reads.
        next_sync_at:
          type:
            - string
            - 'null'
          format: date-time
          description: When the next sync starts. Null while connecting or syncing.
        cost:
          type: object
          description: >-
            What the source's syncs read and what each frequency costs a month,
            at `usd_per_million_rows`.
          required:
            - rows_per_run
            - window_s
            - reads
            - auto_interval_s
            - rows_billed
            - usd_per_million_rows
            - options
          properties:
            rows_per_run:
              type:
                - integer
                - 'null'
              description: Rows the last finished sync read from the app.
            window_s:
              type:
                - integer
                - 'null'
              description: >-
                Seconds that sync covered since the one before. Null after a
                first sync.
            reads:
              type:
                - string
                - 'null'
              enum:
                - changes
                - everything
                - null
              description: >-
                Whether a sync reads only what changed or every record. Null
                until the second sync.
            auto_interval_s:
              type:
                - integer
                - 'null'
              description: The automatic interval, to compare yours with.
            usd_per_million_rows:
              type: number
              description: The price of a million rows read.
              examples:
                - 100
            options:
              type: array
              description: The automatic frequency first, then each frequency on offer.
              items:
                type: object
                required:
                  - interval_s
                  - auto
                  - rows_month
                  - usd_month
                properties:
                  interval_s:
                    type: integer
                    description: >-
                      Seconds between syncs; 0 for automatic before a sync sets
                      it.
                  auto:
                    type: boolean
                  rows_month:
                    type:
                      - integer
                      - 'null'
                    description: >-
                      Rows a month at this frequency. Null until a measured
                      sync.
                  usd_month:
                    type:
                      - number
                      - 'null'
                    description: >-
                      The month's cost at this frequency. Null until a measured
                      sync.
            rows_billed:
              type: boolean
              description: >-
                False when Conare reads the app directly and its rows cost
                nothing.
    Run:
      type: object
      required:
        - id
        - source_id
        - kind
        - trigger
        - state
        - phase
        - attempt
        - sweep
        - sweep_reason
        - expected
        - counts
        - error
        - created_at
        - started_at
        - finished_at
      properties:
        id:
          type: string
          examples:
            - run_8c1e0f3a2b4d5c6e7f8a9b0c
        source_id:
          type:
            - string
            - 'null'
        kind:
          type: string
          enum:
            - snapshot
            - import
            - delete
            - purge
        trigger:
          type: string
          enum:
            - api
            - schedule
            - janitor
            - purge
            - connect
        state:
          type: string
          enum:
            - queued
            - running
            - succeeded
            - failed
            - canceled
        phase:
          type:
            - string
            - 'null'
          examples:
            - receiving
            - sweeping
            - draining
            - deleting
            - waiting
            - verifying
            - reverifying
        attempt:
          type: integer
        sweep:
          type: string
          enum:
            - none
            - applied
            - held
            - blocked
          description: >-
            A snapshot's deletes: `applied`, `held` (over 10% and 1,000 at once,
            until a run 24 h later agrees) or `blocked` (none).
        sweep_reason:
          type:
            - string
            - 'null'
        expected:
          type:
            - integer
            - 'null'
          format: int64
        counts:
          type: object
          description: >-
            What the run did, e.g. `seen`, `planned`, `deleted`; an import's
            `lines`, `created`, `updated`, `rejected`.
          additionalProperties:
            type: integer
        error:
          type:
            - object
            - 'null'
          description: '`{code, message}` of a failed run.'
        progress:
          type: object
          description: A running import's progress, measured over the last minute.
          properties:
            done:
              type: integer
            expected:
              type: integer
            rate_per_s:
              type: number
            eta_s:
              type: number
            eta_is_estimate:
              type: boolean
              const: true
        created_at:
          type: string
          format: date-time
        started_at:
          type:
            - string
            - 'null'
          format: date-time
        finished_at:
          type:
            - string
            - 'null'
          format: date-time
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - request_id
          properties:
            code:
              type: string
              description: >
                Stable, machine-readable, by status:


                - 400: `invalid_request`, `fetch_failed`, `invalid_json`,
                `invalid_namespace`, `invalid_id`, `invalid_metadata`,
                `invalid_filter`, `invalid_cursor`, `invalid`, `md5_mismatch`,
                `idempotency_key_required`, `invalid_path`

                - 401: `unauthorized`, `invalid_upload`

                - 402 (billed calls only): `credits_exhausted`,
                `spend_cap_reached`, `monthly_limit_reached`, `payment_failed`

                - 403: `forbidden`, `namespace_forbidden`,
                `key_scope_models_only`, `namespace_not_allowed`

                - 404: `namespace_not_found`, `document_not_found`,
                `source_not_found`, `model_not_found`, `key_not_found`,
                `file_not_found`, `parse_not_found`, `not_found`

                - 405: `method_not_allowed`

                - 409: `version_conflict`, `conflict`,
                `idempotency_in_progress`, `run_active`, `run_not_receiving`,
                `source_deleting`, `user_purging`, `upload_incomplete`,
                `namespace_has_sources`, `too_many_exclusions`, `push_source`,
                `pull_source`, `files_source`, `no_original`, `file_replaced`,
                `gcs_bucket_claimed`, `limit_reached`

                - 410: `upload_expired`, `model_retired`

                - 413: `payload_too_large`, `too_large`

                - 415: `unsupported_file`, `type_mismatch`,
                `unsupported_encoding`

                - 422: `idempotency_key_reused`, `no_text`, `unreadable_file`,
                `password_protected`, `gcs_access_denied`, `gcs_not_verified`,
                `gcs_bucket_not_found`

                - 429: `rate_limited`

                - 500: `internal_error`; 502: `upstream_error`; 501:
                `models_only`

                - 503: `unavailable`, `sources_unavailable`, `timeout`,
                `embed_unavailable`, `sync_storage_unavailable`,
                `sync_unconfigured`, `files_unconfigured`, `files_unavailable`,
                `gcs_unconfigured`, `gcs_unavailable`, `gcs_auth_failed`
            message:
              type: string
            request_id:
              type: string
    NamespaceName:
      type: string
      pattern: ^[a-z0-9][a-z0-9_-]{0,63}$
      description: 1-64 characters of `a-z 0-9 _ -`, starting with a letter or digit.
      examples:
        - docs
        - user-42
  responses:
    Error:
      description: An error. `X-Request-Id` is also in the response headers.
      headers:
        X-Request-Id:
          schema:
            type: string
        Retry-After:
          description: Seconds to wait before retrying (429, 503).
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: invalid_request
              message: text is required
              request_id: 7d0f4c1e-2b8a-4e39-9a61-3c5e8b2f9d04
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: sk-conare-…
      description: >-
        A key from conare.ai/dashboard/keys with full access, some namespaces,
        or models only (`/embed`, `/rerank`, `/v1`, `/v2/rerank`, `/parse`).

````

## Related topics

- [Set how often a source syncs](https://docs.conare.ai/es/api-reference/sources/set-how-often-a-source-syncs.md)
- [Delete a source's documents](https://docs.conare.ai/es/api-reference/custom-sources/delete-a-sources-documents.md)
- [List sources](https://docs.conare.ai/es/api-reference/sources/list-sources.md)
- [Get a source](https://docs.conare.ai/es/api-reference/sources/get-a-source.md)
- [Connect a source](https://docs.conare.ai/es/api-reference/sources/connect-a-source.md)


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