{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/argus-town/json-schema/argus-town-connect-link-schema.json",
  "title": "ConnectLink",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/argus-town-openapi.json#/components/schemas/ConnectLink",
  "type": "object",
  "required": [
    "object",
    "id",
    "provider",
    "credential_type",
    "label",
    "status",
    "connection",
    "expires_at",
    "next_steps"
  ],
  "properties": {
    "object": {
      "type": "string",
      "enum": [
        "connect_link"
      ]
    },
    "id": {
      "type": "string"
    },
    "provider": {
      "type": "string"
    },
    "credential_type": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "label": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "submitting",
        "done",
        "expired",
        "locked"
      ]
    },
    "connection": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "$ref": "#/$defs/Connection"
        },
        {
          "type": "null"
        }
      ],
      "description": "The connection once the human has pasted the credential (`done`): its id, or the object with `expand[]=connection`."
    },
    "url": {
      "type": "string",
      "description": "Where the human pastes the credential. Returned only when the link is created; it cannot be read back."
    },
    "expires_at": {
      "type": "string",
      "format": "date-time"
    },
    "next_steps": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/NextStepItem"
      }
    }
  },
  "additionalProperties": true,
  "$defs": {
    "Advisory": {
      "type": "object",
      "required": [
        "level",
        "code",
        "message"
      ],
      "properties": {
        "level": {
          "type": "string",
          "enum": [
            "info",
            "warning",
            "critical"
          ]
        },
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      },
      "additionalProperties": true
    },
    "BreakdownRow": {
      "type": "object",
      "required": [
        "period_start",
        "dimension",
        "dimension_key",
        "spend_usd",
        "requests",
        "tokens"
      ],
      "properties": {
        "period_start": {
          "type": "string",
          "format": "date-time"
        },
        "dimension": {
          "type": "string"
        },
        "dimension_key": {
          "type": "string"
        },
        "spend_usd": {
          "type": "number"
        },
        "requests": {
          "type": "number"
        },
        "tokens": {
          "type": "number"
        }
      },
      "additionalProperties": true
    },
    "Connection": {
      "type": "object",
      "required": [
        "object",
        "id",
        "provider",
        "origin",
        "label",
        "credential_type",
        "status",
        "status_detail",
        "last_synced_at",
        "created_at",
        "updated_at"
      ],
      "properties": {
        "object": {
          "type": "string",
          "enum": [
            "connection"
          ]
        },
        "id": {
          "type": "string"
        },
        "provider": {
          "type": "string"
        },
        "origin": {
          "type": "string",
          "enum": [
            "poll",
            "push",
            "both"
          ]
        },
        "label": {
          "type": "string"
        },
        "credential_type": {
          "type": "string"
        },
        "status": {
          "type": "string"
        },
        "status_detail": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "last_synced_at": {
          "anyOf": [
            {
              "type": "string",
              "format": "date-time"
            },
            {
              "type": "null"
            }
          ]
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        },
        "updated_at": {
          "type": "string",
          "format": "date-time"
        },
        "metrics": {
          "$ref": "#/$defs/Metrics"
        },
        "metered": {
          "type": "boolean"
        },
        "advisories": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Advisory"
          }
        },
        "usage": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/UsageDay"
          }
        },
        "breakdown": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/BreakdownRow"
          }
        },
        "rate_limits": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/RateLimitReading"
          }
        },
        "sync_runs": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Sync"
          }
        },
        "plan": {
          "anyOf": [
            {
              "$ref": "#/$defs/Plan"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "additionalProperties": true
    },
    "Metrics": {
      "type": "object",
      "required": [
        "balance_usd",
        "burn_per_day",
        "days_to_zero",
        "mtd_spend_usd",
        "spend_basis",
        "observed_since",
        "balance_scope",
        "projected_month_end_usd",
        "wow_change_pct",
        "rate_limit_headroom_pct",
        "error_rate_pct",
        "accuracy",
        "cost_drift_pct",
        "billing_mode",
        "utilization_pct",
        "used_amount",
        "included_amount",
        "included_meter_id",
        "subscription_fee_usd",
        "effective_usd_per_unit",
        "days_to_reset",
        "recommended_action",
        "recommended_tier",
        "recommended_delta_usd"
      ],
      "properties": {
        "balance_usd": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ]
        },
        "burn_per_day": {
          "type": "number"
        },
        "days_to_zero": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ]
        },
        "mtd_spend_usd": {
          "type": "number"
        },
        "spend_basis": {
          "type": "string",
          "enum": [
            "reported",
            "observed_since_connected"
          ]
        },
        "observed_since": {
          "anyOf": [
            {
              "type": "string",
              "format": "date-time"
            },
            {
              "type": "null"
            }
          ]
        },
        "balance_scope": {
          "type": "string",
          "enum": [
            "account",
            "key",
            "unknown"
          ]
        },
        "projected_month_end_usd": {
          "type": "number"
        },
        "wow_change_pct": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ]
        },
        "rate_limit_headroom_pct": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ]
        },
        "error_rate_pct": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ]
        },
        "accuracy": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "cost_drift_pct": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ]
        },
        "billing_mode": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "utilization_pct": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ]
        },
        "used_amount": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ]
        },
        "included_amount": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ]
        },
        "included_meter_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "subscription_fee_usd": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ]
        },
        "effective_usd_per_unit": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ]
        },
        "days_to_reset": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ]
        },
        "recommended_action": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "recommended_tier": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "recommended_delta_usd": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ]
        },
        "right_sizing": {
          "anyOf": [
            {
              "$ref": "#/$defs/RightSizing"
            },
            {
              "type": "null"
            }
          ],
          "description": "The full recommendation behind the `recommended_*` fields. Present only on `GET /v1/connections/{id}` with `expand[]=metrics`."
        }
      },
      "additionalProperties": true
    },
    "NextStepItem": {
      "type": "object",
      "required": [
        "rel",
        "method",
        "href",
        "why"
      ],
      "properties": {
        "rel": {
          "type": "string"
        },
        "method": {
          "type": "string"
        },
        "href": {
          "type": "string"
        },
        "why": {
          "type": "string"
        }
      },
      "additionalProperties": true
    },
    "Plan": {
      "type": "object",
      "required": [
        "object",
        "id",
        "plan_name",
        "tier",
        "rate_limit_tier",
        "in_overage",
        "price_usd",
        "included_meter_id",
        "included_amount",
        "included_period",
        "used_this_period",
        "period_reset_at",
        "rollover",
        "source",
        "captured_at"
      ],
      "properties": {
        "object": {
          "type": "string",
          "enum": [
            "plan"
          ]
        },
        "id": {
          "type": "string"
        },
        "plan_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "tier": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "rate_limit_tier": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "in_overage": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ]
        },
        "price_usd": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ]
        },
        "included_meter_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "included_amount": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ]
        },
        "included_period": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "used_this_period": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ]
        },
        "period_reset_at": {
          "anyOf": [
            {
              "type": "string",
              "format": "date-time"
            },
            {
              "type": "null"
            }
          ]
        },
        "rollover": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "source": {
          "type": "string"
        },
        "captured_at": {
          "type": "string",
          "format": "date-time"
        }
      },
      "additionalProperties": true
    },
    "RateLimitReading": {
      "type": "object",
      "required": [
        "limit_type",
        "limit",
        "remaining",
        "reset_at",
        "observed_at"
      ],
      "properties": {
        "limit_type": {
          "type": "string"
        },
        "limit": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ]
        },
        "remaining": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ]
        },
        "reset_at": {
          "anyOf": [
            {
              "type": "string",
              "format": "date-time"
            },
            {
              "type": "null"
            }
          ]
        },
        "observed_at": {
          "type": "string",
          "format": "date-time"
        }
      },
      "additionalProperties": true
    },
    "RightSizing": {
      "type": "object",
      "required": [
        "action",
        "target_plan_id",
        "target_plan_name",
        "delta_usd_monthly",
        "basis_pct",
        "reason"
      ],
      "properties": {
        "action": {
          "type": "string",
          "enum": [
            "hold",
            "downgrade",
            "upgrade",
            "buy_pack"
          ]
        },
        "target_plan_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "target_plan_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "delta_usd_monthly": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "Monthly cost change versus the current plan; negative is savings."
        },
        "basis_pct": {
          "type": "number"
        },
        "reason": {
          "type": "string"
        }
      },
      "additionalProperties": true
    },
    "Sync": {
      "type": "object",
      "required": [
        "object",
        "id",
        "kind",
        "status",
        "started_at",
        "finished_at",
        "records_written",
        "error"
      ],
      "properties": {
        "object": {
          "type": "string",
          "enum": [
            "sync"
          ]
        },
        "id": {
          "type": "string"
        },
        "kind": {
          "type": "string"
        },
        "status": {
          "type": "string"
        },
        "started_at": {
          "type": "string",
          "format": "date-time"
        },
        "finished_at": {
          "anyOf": [
            {
              "type": "string",
              "format": "date-time"
            },
            {
              "type": "null"
            }
          ]
        },
        "records_written": {
          "type": "number"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "additionalProperties": true
    },
    "UsageDay": {
      "type": "object",
      "required": [
        "period_start",
        "spend_usd",
        "requests",
        "tokens_input",
        "tokens_output",
        "errors",
        "preliminary"
      ],
      "properties": {
        "period_start": {
          "type": "string",
          "format": "date-time"
        },
        "spend_usd": {
          "type": "number"
        },
        "requests": {
          "type": "number"
        },
        "tokens_input": {
          "type": "number"
        },
        "tokens_output": {
          "type": "number"
        },
        "errors": {
          "type": "number"
        },
        "preliminary": {
          "type": "boolean"
        }
      },
      "additionalProperties": true
    }
  }
}