# Create Account

Source: https://recoupable.dev/docs/api-reference/accounts/create

Create a new account or retrieve an existing account by email or wallet address. If an account with the provided email or wallet already exists, returns that account. Otherwise creates a new account and initializes credits.

## POST /api/accounts

Full OpenAPI specification: https://recoupable.dev/docs/spec/accounts.json

## Authentication

The supplied specification does not declare an OpenAPI security object for this operation. Its declared headers and parameters still apply. Consult the authentication guide and the full specification before calling it.

[Authentication guide](https://recoupable.dev/docs/authentication)

## Operation and referenced schemas

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Recoup API - Accounts",
    "description": "API documentation for the Recoup platform - an AI agent platform for the music industry",
    "license": {
      "name": "MIT"
    },
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.recoupable.dev"
    }
  ],
  "paths": {
    "/api/accounts": {
      "post": {
        "description": "Create a new account or retrieve an existing account by email or wallet address. If an account with the provided email or wallet already exists, returns that account. Otherwise creates a new account and initializes credits.",
        "requestBody": {
          "description": "Account credentials to create or lookup",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateAccountRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Account created or retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountDataResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - failed to create account",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "CreateAccountRequest": {
        "type": "object",
        "properties": {
          "email": {
            "type": "string",
            "format": "email",
            "description": "Email address to associate with the account. If an account with this email exists, it will be returned."
          },
          "wallet": {
            "type": "string",
            "description": "Wallet address to associate with the account. If an account with this wallet exists, it will be returned."
          }
        },
        "description": "At least one of email or wallet should be provided to identify or create an account."
      },
      "AccountDataResponse": {
        "type": "object",
        "required": [
          "data"
        ],
        "properties": {
          "data": {
            "$ref": "#/components/schemas/AccountData",
            "description": "The account data"
          }
        }
      },
      "AccountErrorResponse": {
        "type": "object",
        "required": [
          "status",
          "message"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "error"
            ],
            "description": "Status of the request"
          },
          "message": {
            "type": "string",
            "description": "Error message describing what went wrong"
          }
        }
      },
      "AccountData": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "The unique identifier of the account"
          },
          "account_id": {
            "type": "string",
            "format": "uuid",
            "description": "The account ID (same as id, for consistency)"
          },
          "name": {
            "type": "string",
            "description": "Display name of the account"
          },
          "email": {
            "type": "string",
            "format": "email",
            "description": "Email address associated with the account"
          },
          "wallet": {
            "type": "string",
            "description": "Wallet address associated with the account"
          },
          "image": {
            "type": "string",
            "format": "uri",
            "description": "URL of the account's profile image"
          },
          "instruction": {
            "type": "string",
            "description": "Custom instruction or bio"
          },
          "organization": {
            "type": "string",
            "description": "Organization name"
          },
          "job_title": {
            "type": "string",
            "description": "Job title"
          },
          "role_type": {
            "type": "string",
            "description": "Role type"
          },
          "company_name": {
            "type": "string",
            "description": "Company name"
          },
          "knowledges": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Knowledge"
            },
            "description": "Knowledge base files attached to this account"
          }
        }
      },
      "Knowledge": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "description": "URL to the knowledge file"
          },
          "name": {
            "type": "string",
            "description": "Name of the knowledge file"
          },
          "type": {
            "type": "string",
            "description": "MIME type of the file"
          }
        }
      }
    }
  }
}
```