# Directory discovery status

Source: https://docs.musicnerd.net/api-reference/artist-bio/directory-discovery

Directory discovery status

## GET /api/artist/{id}/directory-discovery

Full OpenAPI specification: https://docs.musicnerd.net/spec/artist-bio.json

## Authentication

This operation requires one of the security alternatives in the specification below. Security scheme definitions are included where present in the published specification.

[Authentication guide](https://docs.musicnerd.net/authentication)

## Operation and referenced schemas

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Music Nerd API: artist bio",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://musicnerd-api.vercel.app",
      "description": "Production"
    },
    {
      "url": "https://musicnerd-api-staging.vercel.app",
      "description": "Staging (staging database)"
    }
  ],
  "paths": {
    "/api/artist/{id}/directory-discovery": {
      "get": {
        "summary": "Directory discovery status",
        "operationId": "getDirectoryDiscoveryStatus",
        "security": [
          {
            "privyBearer": []
          }
        ],
        "description": "Whether the research started when an artist was added to the directory is still running, and a fingerprint of the profile's public links that changes when they do. Only the account that added the artist, or an admin, may read it, and only within 24 hours of the artist being added.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The artist's ID (a UUID).",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "example": "aab92f80-f9e1-4299-aa33-7dd85c8de5d3"
          }
        ],
        "responses": {
          "200": {
            "description": "The discovery state and the current link fingerprint. Carries `Cache-Control: private, no-store`.",
            "headers": {
              "Cache-Control": {
                "description": "`private, no-store`.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DirectoryDiscoveryStatus"
                },
                "example": {
                  "status": "ok",
                  "state": "active",
                  "revision": "3f8a2c1d9e0b7a6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c"
                }
              }
            }
          },
          "400": {
            "description": "`id` isn't a UUID.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "status": "error",
                  "error": "Invalid artist"
                }
              }
            }
          },
          "401": {
            "description": "No token, an invalid or expired token, or no Music Nerd user for it.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "status": "error",
                  "error": "Not signed in"
                }
              }
            }
          },
          "404": {
            "description": "Nothing to observe: no such artist, no directory research for it, it was added more than 24 hours ago, or the caller is neither the adding account nor an admin.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "status": "error",
                  "error": "Discovery is unavailable."
                }
              }
            }
          },
          "503": {
            "description": "The status could not be read.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "status": "error",
                  "error": "Discovery could not be checked."
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "DirectoryDiscoveryStatus": {
        "type": "object",
        "required": [
          "status",
          "state",
          "revision"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "ok"
            ]
          },
          "state": {
            "type": "string",
            "enum": [
              "active",
              "complete",
              "failed",
              "stopped"
            ],
            "description": "`active` while directory research jobs are pending or running; `complete` when all finished; `failed` when one gave up; `stopped` once the artist is claimed."
          },
          "revision": {
            "type": "string",
            "description": "A fingerprint of the profile's public link destinations; a change means the links changed."
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "status",
          "error"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "error"
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    },
    "securitySchemes": {
      "privyBearer": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "Access token",
        "description": "The signed-in user's access token. Copy it at https://musicnerd.net/access after signing in. Each operation says who may call it: any signed-in user, or the artist's approved claimant or a Music Nerd admin."
      }
    }
  }
}
```
