openapi: 3.2.0
info:
  title: Datacircle API
  version: '1'
  description: Datacircle is a data co-op.
  termsOfService: https://datacircle.dev/terms
  contact:
    name: Datacircle
    url: https://datacircle.dev
    email: wayne@datacircle.dev
  x-logo:
    url: https://datacircle.dev/favicon.png
    altText: Datacircle
servers:
- url: https://api.datacircle.dev
security:
- token: []
tags:
- name: Datacircle
  description: 'Your Datacircle account: balance, adding funds, files, API key.'
paths:
  /me/api-key/reset/:
    post:
      tags:
      - Datacircle
      summary: Reset your API key
      description: The old key stops working at once.
      responses:
        '200':
          description: '`{"api_key": ...}`'
          content:
            application/json:
              schema:
                type: object
                required:
                - api_key
                properties:
                  api_key:
                    type: string
                    description: 'Your new API key: send it as `Authorization: Token <api_key>`. The old one stopped working when this answered.'
      operationId: postMeApiKeyReset
      x-operation-id-source: derived
  /balance/:
    get:
      tags:
      - Datacircle
      summary: Read the balance
      description: 'Your balance, in dollars: `balance_usd` is everything your calls can spend right now, then what it is made of: what is left of the signup credit, of the funds you added, of manual credits, and every temporary credit with its expiry. Read it to know whether it covers the calls you are about to make. Free.'
      responses:
        '200':
          description: Balance split by kind
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Balance'
      operationId: getBalance
      x-operation-id-source: derived
  /checkout/:
    post:
      tags:
      - Datacircle
      summary: Start a Stripe Checkout
      description: 'Starts a Stripe Checkout that adds funds to your balance, any whole number of dollars from 5 to 10,000. Open `checkout_url`, or hand it to a human to pay: nothing is charged until they do. The funds land in `funds_usd` once Stripe confirms the payment, and never expire.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - amount_usd
              properties:
                amount_usd:
                  description: 'How much to add to your balance, in whole dollars. Add \$50 to your account: you get \$50 of API PLUS the flat file (the co-op files in `GET /files/`).'
                  type: integer
                  minimum: 5
                  maximum: 10000
                  example: 50
      responses:
        '200':
          description: '`{"checkout_url": ...}`: send the browser there'
          content:
            application/json:
              schema:
                type: object
                required:
                - checkout_url
                properties:
                  checkout_url:
                    type: string
                    description: 'The Stripe Checkout page for this payment: open it, or hand it to a human to pay. The funds land in `funds_usd` once Stripe confirms the payment.'
        '400':
          description: Amount not offered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: Stripe refused the checkout session
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Payments are not configured on this server
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: postCheckout
      x-operation-id-source: derived
  /files/:
    get:
      tags:
      - Datacircle
      summary: List files
      description: 'The co-op files (`coop_up2data`, `coop_harvestapi`, `coop_fetchin`): every LinkedIn profile any customer fetched through each provider, new every day. Each has its `id` and `is_unlocked`. Get a file with `POST /files/{file_id}/download-link/`. This call is free.'
      responses:
        '200':
          description: Every file with `is_unlocked` for this workspace
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/File'
      operationId: getFiles
      x-operation-id-source: derived
  /files/{file_id}/download-link/:
    post:
      tags:
      - Datacircle
      summary: Get a download link
      description: 'A download link for one file of `GET /files/`, by its `id`: `url`, signed and valid one hour, fetched as is without your API key, and `next_step`, a ready-to-run call per provider for the live profile behind any row. A file not unlocked for this workspace answers `403`, its `error` saying how to unlock it. Free.'
      parameters:
      - name: file_id
        in: path
        required: true
        description: The file's `id`, from `GET /files/` (List files).
        schema:
          type: integer
      responses:
        '200':
          description: '`{"url": ...}`, valid one hour'
          content:
            application/json:
              schema:
                type: object
                required:
                - url
                - next_step
                properties:
                  url:
                    type: string
                    description: A signed download URL for the file, valid one hour. Fetch it as is, without your API key.
                  next_step:
                    type: object
                    required:
                    - why
                    - curls
                    - docs_url
                    properties:
                      why:
                        type: string
                        description: What the file holds and what your balance can pull for its rows.
                      curls:
                        type: array
                        description: 'One ready-to-run call per provider. Keys never name a provider: providers come and go in the list.'
                        items:
                          type: object
                          required:
                          - provider
                          - curl
                          properties:
                            provider:
                              type: string
                              description: 'The provider the call goes to: `up2data`, `harvestapi` or `fetchin`, its `X-Data-Provider` value.'
                            curl:
                              type: string
                              description: A ready-to-run curl, your API key filled in.
                      docs_url:
                        type: string
                        description: Where Datacircle's docs are (a URL).
                    description: 'What to do with the file next: pull the live LinkedIn profile behind any row, with no markup.'
        '403':
          description: 'Not unlocked for this workspace: `error` says why, and how to unlock it.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: postFilesByFileIdDownloadLink
      x-operation-id-source: derived
components:
  schemas:
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: What went wrong, in plain words.
    Balance:
      type: object
      properties:
        balance_usd:
          type: number
          description: 'Everything you can spend right now, in dollars: `signup_credit_usd` + `funds_usd` + `manual_credit_usd` (permanent) + every `temporary_credits[].credit_usd` (temporary). `datacircle_meta.balance_usd` on a provider call is this number after the call.'
        signup_credit_usd:
          type: number
          description: 'Permanent: what is left of the $5 signup credit every workspace gets once. Never expires.'
        funds_usd:
          type: number
          description: 'Permanent: what is left of the funds you added through Stripe Checkout (`POST /checkout/`). Never expires.'
        manual_credit_usd:
          type: number
          description: 'Permanent: what is left of the credits Datacircle added to your workspace by hand (a refund, a gift, a deal). Never expires. 0 for most workspaces.'
        temporary_credits:
          type: array
          items:
            type: object
            properties:
              campaign:
                type: string
                description: The campaign that gave this credit, by its name.
              credit_usd:
                type: number
                description: 'Temporary: what is left of this credit until `expires_at`, in dollars. Also capped by what is left of the campaign''s shared budget, so it can drop to 0 before then.'
              expires_at:
                type: string
                format: date-time
                description: 'When this grant expires (ISO 8601): after it, what is left is gone.'
          description: 'Temporary credits: one entry per campaign grant that has not expired yet, soonest to expire first. Empty when you have none. At `expires_at` the entry leaves this list and whatever is left of it is gone.'
    File:
      type: object
      properties:
        id:
          type: integer
          description: 'The file''s id: pass it to `POST /files/{file_id}/download-link/`. Every daily file gets a new id. Old ids still download.'
        dataset:
          type: string
          enum:
          - coop_up2data
          - coop_harvestapi
          - coop_fetchin
          description: 'Which dataset this file is a snapshot of: `coop_up2data`, `coop_harvestapi` and `coop_fetchin` are the co-op files: every LinkedIn profile fetched through Up2Data, through HarvestAPI and through Fetchin, one flat Parquet table each (columns: docs Dataset fields), rebuilt every day. `GET /files/` lists the newest file of each dataset.'
        filename:
          type: string
          description: The download's file name, such as `coop_up2data.parquet`.
        row_count:
          type:
          - integer
          - 'null'
          description: Rows in the file. `null` when we have not counted it.
        size_bytes:
          type: integer
          description: The file's size, in bytes.
        sha256:
          type:
          - string
          - 'null'
          description: The file's SHA-256, in hex, to check your download. `null` when we have not measured it.
        created_at:
          type: string
          format: date-time
          description: When the file was exported (ISO 8601).
        is_unlocked:
          type: boolean
          description: 'Whether this workspace may download it: `true` once this workspace has added $50 in funds.'
  securitySchemes:
    token:
      type: http
      scheme: bearer
      description: 'Your API key: `Authorization: Bearer <your API key>`. `Authorization: Token <your API key>` works too.'
externalDocs:
  description: Datacircle docs
  url: https://docs.datacircle.dev